SwiftData模型容器ModelContainer

ModelContainer 是 SwiftData 框架中用于管理数据模型的核心组件。它提供了一种机制来持久化、管理和访问数据，使开发者能够在应用中轻松地实现数据存储和数据绑定。通过使用 ModelContainer，SwiftData 能够处理数据的存储、检索和模型对象的生命周期。

主要功能

1、数据持久化：ModelContainer 可以将数据存储在本地数据库中（例如 SQLite）。它会管理数据的持久化，无需手动编写数据库代码。

2、数据同步：所有使用同一个 ModelContainer 的视图和对象可以共享相同的数据源。这种数据共享确保了数据的一致性和实时同步。比如，视图中数据变化会自动更新到持久化存储中，反之亦然。

3、数据管理：ModelContainer 充当数据访问的中心。可以通过它来创建、更新、查询和删除数据模型实例。

4、数据绑定：ModelContainer 可以绑定到 SwiftUI 的视图中，使数据可以响应用户交互实时更新视图。这样，开发者可以利用 @Environment(\.modelContext) 等 SwiftUI 环境属性轻松访问模型上下文。

使用 ModelContainer

1、定义模型

使用 SwiftData 中的 @Model 属性来标记类或结构体。例如：

import SwiftData

@Model
class UserProfile {
    var name: String
    var age: Int

    init(name: String, age: Int) {
        self.name = name
        self.age = age
    }
}

这里 UserProfile 是一个模型，ModelContainer 将会管理它。

2、初始化 ModelContainer

在应用或视图中创建 ModelContainer 实例，通常是在 App 文件中初始化：

@main
struct MyApp: App {
    let container: ModelContainer

    init() {
        container = try! ModelContainer(for: UserProfile.self)
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .modelContainer(container)
        }
    }
}

App初始化时创建一次，全局使用。

还可以有一种更简洁的写法：

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .modelContainer(for: UserProfile.self)  // 语法糖
        }
    }
}

modelContainer(for:)是一个语法糖，对应的SwiftData完整语句：

.modelContainer(try! ModelContainer(for: UserProfile.self)) // 完整写法

注意：这个简洁的写法，不能配置CloudKit、schema名称、迁移策略等，只能使用本地数据库。

3、数据访问与绑定

在视图中可以通过 @Environment(\.modelContext) 引用 ModelContext，这会自动连接到上级的 ModelContainer。

struct ContentView: View {
    @Environment(\.modelContext) private var context
    @Query var profiles: [UserProfile] // 查询所有用户数据

    var body: some View {
        // 使用 `profiles` 渲染视图
    }
}

常用属性

1、mainContext: ModelContext类型，主线程上的上下文（context），用于容器数据的增删改查：

container.mainContext.insert(user)
try container.mainContext.save()

2、configurations: [ModelConfiguration]类型，描述数据库如何创建、存储位置、CloudKit 配置等。

一个 container 可以挂多个 schema 或多个配置：

let config = ModelConfiguration(
    "UserSchema",
    cloudKitDatabase: .private("iCloud.com.fang.app")
)

3、schemas: [Schema]类型，SwiftData 通过 Schema 表示模型元信息。通常不会使用它，除非做多 Schema Container：

let container = try ModelContainer(
    for: [User.self, Note.self],
    configurations: config
)

4、undoManager: UndoManager?类型，类似AppKit/UIKit 的 UndoManager，只适合在 macOS 或文本编辑类 App 中使用：

container.undoManager?.undo()

SwiftData默认不启用undo，需要明确开启。

5、isCloudKitEnabled（只读）：配置了 CloudKit，这里会自动 true/false。

常用方法

1、init初始化：

let container = try ModelContainer(for: User.self)

多模型初始化：

let container = try ModelContainer(for: [User.self, Note.self])

配置ModelConfiguration的初始化：

let container = try ModelContainer(
    for: [User.self, Note.self],
    configurations: config
)

2、performBackgroundTask：插入大量数据，仅支持 iOS 18 +/macOS 15。

container.performBackgroundTask { context in
    // 这里是后台 context，适合大数据导入
}

#Preview中的ModelContainer

在视图预览时，无法读取真实App的ModelContainer，需要手动创建一个ModelContainer：

#Preview {
    // 创建一个未持久化的内存数据库（避免污染真实数据）
    let config = ModelConfiguration(isStoredInMemoryOnly: true)
    let container = try! ModelContainer(for: UserProfile.self, configurations: config)

    // 添加测试数据
    let context = container.mainContext
    let user = UserProfile(name: "name", age: 20)
    context.insert(user)
    try? context.save()

    return ContentView()
        .modelContainer(container)
}

isStoredInMemoryOnly: true表示预览使用内存数据库，不写入真实的SwiftData。

总结

ModelContainer 是 SwiftData 用于管理数据的核心组件，它负责处理数据的持久化和数据共享。它与 SwiftUI 集成，支持视图的实时数据绑定，简化了数据管理和数据驱动的开发流程。

相关文章

1、SwiftData上下文环境ModelContext：https://fangjunyu.com/2024/11/05/swiftdata%e6%a1%86%e6%9e%b6%e5%b1%9e%e6%80%a7%e5%8c%85%e8%a3%85%e5%99%a8modelcontext/

2、SwiftData配置ModelConfiguration：https://fangjunyu.com/2024/11/06/swiftdata%e7%ae%a1%e7%90%86%e6%95%b0%e6%8d%ae%e6%a8%a1%e5%9e%8b%e7%9a%84%e9%85%8d%e7%bd%ae%e5%af%b9%e8%b1%a1modelconfiguration/

扩展知识

1、类中使用ModelContainer

SwiftUI视图中使用@Environment(\.modelContext)，获取ModelContainer的上下文，并实现UI的相关操作（包括大多数增删改查）。

在非SwiftUI代码中，无法通过@Environment获取，可以通过传参或单例来解决：

1、把context作为参数传入：

func saveUser(name: String, context: ModelContext) {
    let user = User(name: name)
    context.insert(user)
    try? context.save()
}

在SwiftUI中通过 @Environment(\.modelContext) 获取上下文，通过参数进行传递使用。

2、给类注入context：

ViewModel代码：

final class UserManager {
    let context: ModelContext

    init(context: ModelContext) {
        self.context = context
    }

    func addUser() {
        context.insert(User(name: "方君宇"))
        try? context.save()
    }
}

在视图创建实例时，将context注入该实例。

@Environment(\.modelContext) private var context
let manager = UserManager(context: context)

3、单例模式：

创建一个ModelContainer单例：

import SwiftUI
import SwiftData

@MainActor
final class DataController {
    static let shared = DataController()
    let container: ModelContainer
    var context: ModelContext { container.mainContext }
    private init() {
        self.container = try! ModelContainer(
            for: PiggyBank.self,
                 SavingsRecord.self)
    }
}

在类中使用单例获取上下文：

let context = ModelContainer.shared.context