数据持久化

SwiftUI App 本地存储分层：UserDefaults 存偏好、SwiftData / Core Data 存结构化数据、FileManager 存文件。对照 /roadmaps/swift-ui「数据持久化」节点。

学习目标

• 选择合适的存储方案（轻量 vs 关系型）
• 使用 UserDefaults 与 @AppStorage 绑定 UI
• 了解 SwiftData @Model 基础 CRUD
• 在 SwiftUI 中观察持久化数据变化

核心概念

UserDefaults 与 @AppStorage

// 命令式读写
UserDefaults.standard.set("swift-ui-essentials", forKey: "lastTrack")
let slug = UserDefaults.standard.string(forKey: "lastTrack") ?? ""

// SwiftUI 声明式绑定
struct PreferencesView: View {
    @AppStorage("darkMode") private var darkMode = false
    @AppStorage("lastTrack") private var lastTrack = ""

    var body: some View {
        Form {
            Toggle("深色模式", isOn: $darkMode)
            TextField("上次 Track", text: $lastTrack)
        }
    }
}

@AppStorage 自动同步 UserDefaults，Toggle/TextField 变更即时持久化。适合主题、引导标记等小数据。

SwiftData 基础

import SwiftData

@Model
final class Bookmark {
    var title: String
    var url: String
    var createdAt: Date

    init(title: String, url: String) {
        self.title = title
        self.url = url
        self.createdAt = .now
    }
}

struct BookmarkListView: View {
    @Environment(\.modelContext) private var context
    @Query(sort: \Bookmark.createdAt, order: .reverse) private var bookmarks: [Bookmark]
    @State private var newTitle = ""

    var body: some View {
        List {
            ForEach(bookmarks) { item in
                VStack(alignment: .leading) {
                    Text(item.title).font(.headline)
                    Text(item.url).font(.caption).foregroundStyle(.secondary)
                }
            }
            .onDelete(perform: deleteBookmarks)
        }
        .navigationTitle("书签")
        .toolbar {
            Button("添加示例") { addSample() }
        }
    }

    private func addSample() {
        let item = Bookmark(title: "SwiftUI 文档", url: "https://developer.apple.com")
        context.insert(item)
    }

    private func deleteBookmarks(at offsets: IndexSet) {
        for index in offsets {
            context.delete(bookmarks[index])
        }
    }
}

iOS 17+ SwiftData 用 @Model 宏定义实体，@Query 自动查询并驱动 List 刷新。App 入口需 .modelContainer(for: Bookmark.self)。

存储选型

方案	数据量	典型场景
UserDefaults / @AppStorage	极小	主题、上次打开页
SwiftData / Core Data	中到大	书签、课时进度
FileManager	文件	缓存图片、导出
Keychain	敏感小数据	Token（见 ios-essentials）

与 React/SwiftUI 对照

SwiftUI 持久化	Web / React	说明
UserDefaults	localStorage	键值偏好
@AppStorage	useLocalStorage Hook	双向绑定
SwiftData @Query	React Query / SWR	响应式数据源
@Model	ORM Entity	结构化模型
Core Data	IndexedDB + ORM	复杂查询
FileManager	File API	二进制文件

React 无内置 ORM；SwiftData 类似 Prisma + 自动 UI 刷新，List 随数据库变更重绘。

练习

• 用 @AppStorage 记住用户上次选中的 Tab
• 创建 SwiftData LessonProgress 模型，实现增删
• 在 App 入口配置 .modelContainer
• 对比 UserDefaults 与 SwiftData 适用边界

小结

@AppStorage 轻量偏好、SwiftData 结构化持久化、@Query 驱动 List。 下一课 MVVM 与架构。见 swift-ui-essentials。