构建更出色的文稿类 App

了解如何运用 iPadOS 中的最新功能来改进文稿类 App。我们将向你展示如何利用 UIDocument 以及现有的桌面类 iPad 和文稿类 API 为你的 App 增添全新功能。了解如何将数据模型转换为 UIDocument 以及如何使用 UIDocumentViewController 呈现文稿，学习如何将 App 迁移到最新的 API 并探索绝佳实践。

章节

资源

相关视频

WWDC23

UIKit 的新功能

WWDC22

WWDC20

在 SwiftUI 内构建基于文档的 app

Tech Talks

统一类型标识符 - 再介绍

下载

♪ ♪

Michael：大家好欢迎观看本次讲座我是 Michael Ochs 在本次视频中我将谈谈如何编译更为出色的以文档为中心的 App 以文档为中心的 App 是生产力工具中重要的组成部分尤其对于 iPad 而言以文档为中心的 App 共分为 3 类：允许浏览文档的例如文件 App；允许查看内容的例如快速查看；还有同时允许编辑或创建内容的例如 Pages 文稿、Keynote 讲演以及 Numbers 表格本视频将重点介绍查看 App 和编辑 App 的改进并且其中部分内容同时也适用于浏览 App iPadOS 17 引入了新的视图控制器这能自动启用 App 的大量功能并且与 iPadOS 16 所引入的桌面级 iPad API 及现有的以文档为中心的 API 完美契合这款新的视图控制器以模块化的方式进行编译因此你既能利用实用系统默认设置同时也能自定义任何个人操作

想要了解更多有关桌面级 iPad API 的信息欢迎观看 WWDC22 中 “认识桌面级 iPad” 以及“编译桌面级 iPad App”

在 SwiftUI 开发中 DocumentGroup 当前无需任何额外的代码便可支持视图控制器中所有的功能想进一步了解有关 SwiftUI 的信息欢迎观看 WWDC20 中 “在 SwiftUI 中构建基于文档的 App” 以及 WWDC22 中“在 iPad 上使用 SwiftUI：添加工具栏、标题等” 而在 UIKit 中这些功能则是可选择的 UIDocumentViewController 是内容视图控制器的新基类它可与 UIDocument 相结合一同自动配置导航栏这就实现了共享、拖放文档、支持撤消和重做等功能该新基类也支持自动重命名功能在本次视频中你将了解如何使用 UIDocument 以及如何使用 UIDocumentViewController 呈现文档接着我会介绍哪些功能是内置的以及如何进一步自定义这些功能最后我会与你深入探讨如何利用 UIDocument 对现有 App 进行迁移首先我们从创建文档开始

对于基于文档的 App 而言核心均为 UIDocument UIDocument 是一个抽象的基类可用于为 App 所支持的每种文件类型创建子类所有 UIDocument 均可由 URL 支持虽然大部分情况下使用的都是磁盘上的文件但你也可以使用数据库和自定义 URL 方案来保存和加载文档 UIDocument 的加载和保存操作是异步的所以如果有必要这可以实现较长时间的读写操作因此 UIDocument 是线程安全的并且可以通过锁和队列协调访问

在实现 UIDocument 子类时你需要注意这两点：加载和保存文档以及提供对文档内容的访问权限所有文档的加载和保存都非常相似而内容的访问则会更具体地取决于文档类型以及文档在 App 中的使用方式例如 Markdown 编辑器所使用的文档类型可能只支持一种文本属性或者也可以公开一个更为复杂的接口以供更新文档中各个单独的部分在我们深入了解内容访问前我们先来谈谈加载和保存对于简单的基于文件的文档你有两种简便的重写方法你可以在打开文档时调用 “loadFromContents:ofType:” 并获取文件内容你也可以在保存文档时调用“contentsForType:” 获取文档当前内容文档内容可以是常规文件的 Data 对象也可以是用于其他内容的 FileWrapper 对象想进一步了解更多有关文件类型及其工作原理的信息欢迎观看 “统一类型标识符 -- 再次介绍” 技术讲座例如在这里文档处理的是常规 Markdown 文件所以我们希望使用一个 Data 对象现在如果你想获得全部权限重写 “saveToURL:forSaveOperation:” 以及“readFromURL:”后你便可以完整访问 URL 并处理其中所有的读写操作如果你想将文档存储在数据库中或对文档的读写操作有特定的要求该方法也十分有效需要注意的是虽然保存操作是异步的但是在方法返回时读取操作应该已经完成以上是加载和保存文档的全部内容现在我们需要找到一种可以访问文档内容的方法一种访问文档内容的简单方法就是为该内容添加属性在这个例子中我添加了一个包含完整 Markdown 字符串的文本属性正如前面幻灯片中所介绍的该属性需在初次加载文档时设置这样每当用户对文档进行编辑 App 便会更新该文本为了让 UIDocument 知道何时需要进行保存每当属性更新时调用 “updateChangeCount:”即可调用“updateChangeCount:” UIDocument 可以将文档标记为需要保存并在适当时候将文本进行自动保存

接下来我们来谈谈使用新 UIDocumentViewController 呈现文档

与 UIDocument 类似 UIDocumentViewController 也是一个抽象基类可用于创建子类该基类负责文档打开、保存和关闭它用来自相关文档的信息填充其导航项目其中包括标题、导航项目的标题菜单、 UIDocumentProperties 对象以及重命名委托此外 UIDocumentViewController 还提供了常见操作的快捷键例如撤销和重做接着我们来看看如何实现 UIDocumentViewController 的子类

你的子类共有两种方法进行重写第一种方法你可以在打开与视图控制器关联的文档时或将已打开的文档分配到新的视图控制器时调用“documentDidOpen” 在该方法中填充视图控制器的视图即可展示文档中的内容需要注意的是在调用“documentDidOpen”和加载视图控制器的视图之间并没有确定的时间顺序如果你想要编写稳健的代码其中一个不错的方式就是将视图配置移到其自己的方法中并从“documentDidOpen”和 “viewDidLoad”中进行调用并且在配置视图前你需要检查视图是否已加载以及文档是否已打开

第二种方法就是重写 “navigationItemDidUpdate” 每当 UIDocumentViewController 需要对导航项目进行更改时便会调用该方法你可以在其中添加自定义导航项目随后 “UIDocumentViewController” 便会尽力减少对导航项目的更改以尽可能保持你的更改此外 UIDocumentViewController 还提供“undoRedoItemGroup” 如果你想要显示撤销和重做按钮将其放入导航栏中即可并且你需要确保文档已获得分配给它的撤销管理器 UIDocumentViewController 将会根据是否存在可用的撤销管理器来改变该组中“hidden”的属性在必要时启用或禁用该组中的按钮

UIDocumentViewController 可以自动打开和关闭文档但如果你需要从视图控制器外部访问文档调用“openDocumentWithCompletionHandler” 便可实现 UIDocumentViewController 在必要时会进行回调例如调用“documentDidOpen” 并且在准备好后调用已完成的处理程序

最后 UIDocumentViewController 还可以提供文档属性并且该属性始终指向与视图控制器相关联的文档虽然你可以在初始化时提供文档但这一步完全是可选的当不存在与视图控制器相关联的文档该属性便会自动显示为空状态想要进一步了解有关配置空状态的信息欢迎观看“UIKit 中的新功能” 此外 UIDocumentViewController 可以作为 App 的根视图控制器假如层次结构中没有浏览器视图控制器 UIDocumentViewController 便会在导航栏中添加一个文档按钮用于打开文档选择器这就需要在 App 的 info.plist 中声明与相关文件类型对应的 “UIDocumentClass”键并将其设置为与该文件类型匹配的 UIDocument 子类

在 iPadOS 17 中 UIDocument 遵循 “UINavigationItemRenameDelegate” 并且其会在用户从标题菜单中调用重命名时自行处理底层文件更改如果你使用的是 UIDocumentViewController 它便会自动为你配置重命名或者你也可以手动将文档设置为导航项目的重命名委托

以上是你在 iPadOS 17 创建以文档为中心的出彩 App 所需要的部分接下来我们来谈谈如何对现有的 App 进行迁移

迁移你的 App 以充分利用 UIDocumentViewController 这个过程十分简单只需要三步第一步更新内容视图控制器的基类第二步将现有代码移到新的回调中第三删除不再需要的代码我们来看看如何对桌面级 iPad App 视频中使用的 Markdown 编辑器示例进行转换如果你对此并不熟悉不用担心接下来我首先会为你介绍现有代码中的相关部分

在这里我们有了对顶部视图控制器的定义、由该控制器定义的 document 属性以及设置初始文档的 init 方法并且我们在文档中添加了一个回调

首先我们将基类改为 UIDocumentViewController

现在该类便会继承自 UIDocumentViewController 但我们会收到一个编译器错误提醒因为属性“document” 已在超类中存在且具有不同的类型我们将该属性的名称改得更具体些比如“markdownDocument” 然后我们将其设置为计算属性并将通用的文本属性更改为该视图控制器中使用的特定文本类该代码中最后需要注意的一点是初始化定式并且其中我们需要使用的最后一部分是为文档分配回调由于文档在视图控制器的生命周期中会发生更改因此我们将此操作移动到每次文档更改时执行

一种简单的方法就是重写文本属性并添加 didSet 回调很好现在基类已经更新到最新了接着我们要做的就是处理新的回调在“viewDidLoad”中我们在导航栏中添加按钮并进行配置从而在工具栏中实现了自定义对于 UIDocumentViewController 我们会将其移到新的回调 “navigationItemDidUpdate”中

接着我们的类已经有了一个方法 “didOpenDocument” 并且该方法几乎和 UIDocumentViewController 中的完全相同因此我们只需要对该方法重命名并调整当前文档可选择的事实

好了接下来是大家最喜欢的部分：删除代码编辑器视图控器遵循 'UINavigationItemRenameDelegate' 但我们不再需要这个协议了因为 UIDocument 会自动为我们处理所有的重命名所以我们删除委托定义、委托方法的所有代码以及“renameDelegate”分配

接着我们还可以删除更多 navigationItem 自定义配置由于“style” 及“backAction” 均由文档视图控制器自动配置所以我们可以将其完全删除

此外还有一个用于创建 UIDocumentProperties 的 “updateDocumentProperties”方法并且该方法要从多个地方进行调用但在这里我们也不需要此方法了 UIDocumentViewController 会为我们完成所有的操作所以我们删除该方法及其调用站点以上便是我们需要完成的内容现在编辑器视图控制器就只能处理 App 特定的功能了它无需处理文档管理的基本任务以及导航栏的默认配置你可以专注于 App 中独特且关键的部分以上便是你需要了解的全部内容据此内容你可以将以文档为中心的 App 提升到全新水平并为用户提供出色体验

对你的数据模型进行转换以利用 UIDocument 接着对内容视图控制器进行转换以利用新的 UIDocumentViewController 基类最后查看视图控制器并移除不需要的代码感谢你的观看 ♪ ♪

3:54 - Loading a document

override func load(fromContents contents: Any, ofType typeName: String?) throws {
    // Load your document from contents
    guard let data = contents as? Data,
          let text = String(data: data, encoding: .utf8) else {
        throw DocumentError.readError
    }
    self.text = text
}

4:08 - Saving a document

override func contents(forType typeName: String) throws -> Any {
    // Encode your document with an instance of NSData or NSFileWrapper
    guard let data = self.text?.data(using: .utf8) else {
        throw DocumentError.writeError
    }
    return data
}

4:34 - Manually saving and loading a document

override func save(to url: URL,
                   for saveOperation: UIDocument.SaveOperation,
                   completionHandler: ((Bool) -> Void)? = nil) {
    self.performAsynchronousFileAccess {
        // Set up file coordination and write file to URL
   }
}

override func read(from url: URL) throws {
    // Set up file coordination and read file from URL
}

5:08 - Defining document that require saving

class Document: UIDocument {
    var text: String? {
        didSet {
            if oldValue != nil && oldValue != text {
                self.updateChangeCount(.done)
            }
        }
    }
}

6:30 - Updating the view hierarchy for a document

override func documentDidOpen() {
    configureViewForCurrentDocument()
}

override func viewDidLoad() {
    super.viewDidLoad()
    configureViewForCurrentDocument()
}

func configureViewForCurrentDocument() {
    guard let document = markdownDocument,
          !document.documentState.contains(.closed)
            && isViewLoaded else { return }
    // Configure views for document
}

7:17 - Updating navigation items for a document

override func navigationItemDidUpdate() {
    // Customize navigation item
}

8:01 - Manually opening a document

documentController.openDocument { success in
    if success {
        self.present(documentController, animated: true)
    }
}

9:20 - Renaming a UIDocument without UIDocumentViewController
```
navigationItem.renameDelegate = document
```

正在查找特定内容？在上方输入一个主题，就能直接跳转到相应的精彩内容。