SwiftUI文档类型DocumentGroup

DocumentGroup 是 SwiftUI 提供的一个专为文档类型应用（Document-based App） 设计的入口结构，用于创建支持打开、保存、编辑文档文件的应用，主要适用于：

macOS（类 Pages、Xcode、Numbers）

iOS/iPadOS（类 Notes、Files、Pages）

基本功能

DocumentGroup 是 SwiftUI 的 @main App 中用于初始化文档应用的方式，它会自动处理：

1、打开文档：支持 macOS 和 iOS 的“打开文件”功能。

2、创建新文档：自动添加“新建文档”菜单。

3、保存文档：自动提供保存机制。

4、多窗口支持（macOS）：每个文档一个窗口。

5、快速实现文档架构：无需手动实现 NSDocumentController 或 UIDocumentBrowserViewController。

基本结构

@main
struct MyApp: App {
    var body: some Scene {
        DocumentGroup(newDocument: MyDocument()) { file in
            ContentView(document: file.$document)
        }
    }
}

1、DocumentGroup(newDocument: MyDocument())

DocumentGroup(newDocument: MyDocument())

DocumentGroup(…) 用于创建“文档结构”的App，newDocument：MyDocument() 表示创建新文档时，用这个类型初始化。

2、file in ContentView(document: file.$document)

{ file in
    ContentView(document: file.$document)
}

定义每次打开一个文件时，用哪个View来展示，将文档内容作为 @Binding 传入主视图，支持实时更新。

3、MyDocument结构，必须实现FileDocument协议

import UniformTypeIdentifiers

struct MyDocument: FileDocument {
    static var readableContentTypes: [UTType] { [.plainText] }

    var text: String = ""

    init() {}

    init(configuration: ReadConfiguration) throws {
        if let data = configuration.file.regularFileContents {
            text = String(decoding: data, as: UTF8.self)
        }
    }

    func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper {
        let data = Data(text.utf8)
        return .init(regularFileWithContents: data)
    }
}

FileDocument是SwiftUI的协议，用于声明一个文档类型的结构，实现它可以让SwiftUI打开文件和保存文件。

1）导入UniformTypeIdentifiers，引入UTType类型，如 .plainText, .image 等。

import UniformTypeIdentifiers

2）实现FileDocument协议：

struct MyDocument: FileDocument

3）支持的文档类型：

static var readableContentTypes: [UTType] { [.plainText] }

表示只打开 .txt（纯文本）类型。

4）文档保存的实际内容：

var text: String = ""

这里文档的内容由文本字符串保存。

5）文档初始化：

init()

新建文档时调用，默认内容为空。

6）打开已有文档时：

init(configuration: ReadConfiguration)

打开已有文档时调用，读取磁盘上的数据。

7）保存文档时调用：

fileWrapper(configuration:)

保存文档时调用，把txt写入一个FileWrapper（文件包）。

文档View示例

struct ContentView: View {
    @Binding var document: MyDocument

    var body: some View {
        TextEditor(text: $document.text)
            .padding()
    }
}

这个界面会自动在修改内容后变“有更改”，并支持保存（Cmd+S）或自动保存。

支持的文档功能

1、打开/保存文件，适用于iOS / macOS。

2、新建文档，适用于macOS / iOS。

3、多窗口支持（每文档一窗口），适用于macOS。

4、自动保存，适用于macOS（AppKit风格）。

5、自定义文件类型，通过 UTType实现，适用于全平台。

6、多文件导入，适用于iOS 16+。

使用场景

1、富文本编辑器。

2、Markdown 编辑器。

3、图像编辑器。

4、结构化 JSON 文件管理

5、数据表格（如 Numbers 类应用）

注意事项

1、DocumentGroup 仅在 SwiftUI 应用中使用（@main App）。

2、不适合复杂文档嵌套结构（如多文件项目，推荐 NSDocument）。

3、文档类型必须 conform to FileDocument。

4、文件类型必须注册（.readableContentTypes）。

总结

DocumentGroup是SwiftUI的文档型App启动结构，通过FileDocument管理文档读取与写入的协议。

支持打开、保存、新建、窗口管理、文档绑定等功能。

相关文章

1、macOS构建文档的NSDocument：https://fangjunyu.com/2025/07/03/macos%e6%9e%84%e5%bb%ba%e6%96%87%e6%a1%a3%e7%9a%84nsdocument/

2、macOS文档控制器NSDocumentController：https://fangjunyu.com/2025/07/03/macos%e6%96%87%e6%a1%a3%e6%8e%a7%e5%88%b6%e5%99%a8nsdocumentcontroller/

3、SwiftUI文档类型协议FileDocument：https://fangjunyu.com/2025/07/05/swiftui%e6%96%87%e6%a1%a3%e7%b1%bb%e5%9e%8b%e5%8d%8f%e8%ae%aefiledocument/