数据持久化方案解析（八） —— UIDocument的数据存储（一）

版本记录

版本号	时间
V1.0	2019.08.25 星期日

前言

数据的持久化存储是移动端不可避免的一个问题，很多时候的业务逻辑都需要我们进行本地化存储解决和完成，我们可以采用很多持久化存储方案，比如说plist文件（属性列表）、preference（偏好设置）、NSKeyedArchiver（归档）、SQLite 3、CoreData，这里基本上我们都用过。这几种方案各有优缺点，其中，CoreData是苹果极力推荐我们使用的一种方式，我已经将它分离出去一个专题进行说明讲解。这个专题主要就是针对另外几种数据持久化存储方案而设立。
1. 数据持久化方案解析（一） —— 一个简单的基于SQLite持久化方案示例（一）
2. 数据持久化方案解析（二） —— 一个简单的基于SQLite持久化方案示例（二）
3. 数据持久化方案解析（三） —— 基于NSCoding的持久化存储（一）
4. 数据持久化方案解析（四） —— 基于NSCoding的持久化存储（二）
5. 数据持久化方案解析（五） —— 基于Realm的持久化存储（一）
6. 数据持久化方案解析（六） —— 基于Realm的持久化存储（二）
7. 数据持久化方案解析（七） —— 基于Realm的持久化存储（三）

Overview

UIDocument用于管理应用数据的离散部分的抽象基类。

首先看下框架基本信息

使用UIDocument及其底层架构的应用程序可为其文档带来许多好处：

• 异步读取和写入后台队列(background queue)上的数据。因此，在进行读写操作时，应用程序对用户的响应性不会受到影响。
• 协调读取和写入与云服务自动集成的文档文件。
• 支持发现文档的不同版本之间的冲突（如果发生）。
• 通过首先将数据写入临时文件然后用它替换当前文档文件来安全地保存文档数据。
• 在适当的时刻自动保存文档数据；这种机制包括支持处理暂停行为。

在Model-View-Controller设计模式中，UIDocument对象是模型对象或模型控制器对象 - 它管理文档的数据或共同构成文档数据的聚合模型对象。您通常将其与视图控制器配对，该视图控制器管理显示文档内容的视图。 UIDocument不支持管理文档视图。

基于文档的应用程序包括可以生成多个文档的应用程序，每个文档都有自己的文件系统位置。基于文档的应用程序必须为其文档创建UIDocument的子类。有关详细信息，请参阅下面的Subclassing Notes。

注意：如果使用数据库存储文档数据，请创建UIManagedDocument类的子类而不是UIDocument；UIManagedDocument是UIDocument的子类。

UIDocument体系结构中文档的主要属性是其文件URL。 通过调用initWithFileURL:初始化文档子类的实例时，必须传递在应用程序沙箱中查找文档文件的文件URL。 UIDocument从文件URL确定文件类型（与文件扩展名关联的统一类型标识符）和文档名称（文件名组件）。 您可以覆盖fileType和localizedName属性的访问器方法以提供不同的值。

以下概述了典型document的生命周期（有关实现细节，请参阅Subclassing Notes）：

• 1） 您可以创建新文档或打开现有文档。

  • 要创建新文档，请分配并初始化子类的实例，然后在实例上调用saveToURL:forSaveOperation:completionHandler:。
  • 要打开现有文档（由用户选择），请分配并初始化子类的实例，然后在实例上调用 openWithCompletionHandler:。

• 2） 用户编辑文档。

  • 在用户编辑时，跟踪对文档的更改。 UIDocument会定期记录何时有未保存的更改并将文档数据写入其文件。

• 3） 用户请求将文档与云服务集成（可选）。

  • 您必须启用云存储文档。 您还必须解决同一文档的不同版本之间的任何冲突。

• 4） 用户关闭文档。

  • 在文档实例上调用closeWithCompletionHandler:，如果有任何未保存的更改，UIDocument将保存文档。

典型的基于文档的应用程序在主线程上调用openWithCompletionHandler:，closeWithCompletionHandler:和saveToURL:forSaveOperation:completionHandler:。当这些方法启动的读取或保存操作结束时，完成处理程序块在调用该方法的同一调度队列上执行，允许您根据读取或保存操作完成任何任务。如果操作不成功，则将NO传递到完成 - 处理(completion-hander)程序块。

---

Implementation of the NSFilePresenter Protocol

UIDocument类采用NSFilePresenter协议。当另一个客户端尝试读取基于UIDocument的应用程序的文档时，该读取将暂停，直到UIDocument对象有机会保存对该文档所做的任何更改。

虽然有些实现什么都不做，但UIDocument实现了所有NSFilePresenter方法。具体来说，UIDocument：

• 实现relinquishPresentedItemToReader:转发传入的块以执行performAsynchronousFileAccessUsingBlock:。
• 实现relinquishPresentedItemToWriter:检查文件修改日期是否已更改；如果文件比以前更新，则调用revertToContentsOfURL:completionHandler:将fileURL的值作为URL参数。
• 实现presentedItemDidMoveToURL:更新文档的文件URL（fileURL）。

在您的UIDocument子类中，如果重写NSFilePresenter方法，则始终可以调用超类实现（super）。

---

Subclassing Notes

每个基于文档的应用程序必须创建UIDocument的子类，其实例表示其文档。大多数应用程序的子类化要求很简单：

• 对于编写操作，请实现contentsForType:error:方法以提供文档数据的快照。数据必须采用NSData对象（对于平面文件）或NSFileWrapper对象（对于文件包）的形式。写操作通常通过自动保存功能启动。
• 对于读取操作，实现loadFromContents:ofType:error:方法以接收NSData或NSFileWrapper对象并使用它初始化应用程序的数据结构。
• 实施更改跟踪以启用自动保存功能。有关详情，请参阅 Change Tracking
• 为文档启用云服务时，解决文档的不同版本之间的冲突。有关详细信息，请参阅 Conflict Resolution and Error Handling。

contentsForType：error：和loadFromContents：ofType：error：通常在主队列上调用方法。进一步来说：

• 在调用saveToURL:forSaveOperation:completionHandler:方法的队列上调用contentsForType：error：方法；数据写入发生在后台线程上。
• 在调用openWithCompletionHandler:方法的队列上调用loadFromContents：ofType：error：方法。

如果您对读取和写入contentsForType：error：和loadFromContents：ofType：error：方法的文档数据有特殊要求，则可以重写UIDocument类的其他方法。有关这些要求和方法的讨论，请参阅Advanced Overrides。

1. Change Tracking

要启用UIDocument的自动保存功能，您必须在用户更改文档时通知它。 UIDocument定期检查hasUnsavedChanges方法是否返回YES; 如果是，则启动文档的保存操作。

在UIDocument子类中实现更改跟踪有两种主要方法：

• 调用NSUndoManager类的方法来实现文档的撤消和重做。 您可以从undoManager属性访问默认的NSUndoManager对象。 这是首选方法，尤其适用于已支持撤消和重做的现有应用程序。
• 在代码中的相应接口处调用updateChangeCount:方法。

2. Conflict Resolution and Error Handling

UIDocument对象在其生命周期中的任何时刻都具有特定状态。您可以通过查询documentState属性来检查当前状态，并通过观察UIDocumentStateChangedNotification通知获得有关更改的通知。

如果为iCloud启用了文档，则检查是否存在冲突版本并尝试解决冲突非常重要。通过侦听UIDocumentStateChangedNotification通知然后检查文档状态是否为UIDocumentStateInConflict来执行此操作。此状态表示文档存在冲突版本，您可以通过调用NSFileVersion类方法unresolvedConflictVersionsOfItemAtURL：来访问该文档，并传入文档的文件URL。如果您无需用户交互即可正确解决冲突，请执行此操作。否则，离散地通知用户存在冲突并让他们选择如何解决冲突。可能的方法包括：

• 显示冲突的版本，用户可以从中选择一个或两个版本来保留
• 显示合并版本并为用户提供选择它的选项
• 显示文件修改日期并为用户提供选择其中一个或两个的选项

除了指示文件间冲突之外，文档状态可以指示错误。例如，UIDocumentStateClosed表示读取时出错，UIDocumentStateSavingError表示保存或还原文档时出错。通过传递给openWithCompletionHandler：，closeWithCompletionHandler：，revertToContentsOfURL：completionHandler：和saveToURL：forSaveOperation：completionHandler：方法的完成处理程序的success参数，通知您的应用程序读取和写入错误。

您可以通过调用或实现 handleError:userInteractionPermitted:方法来处理错误；此方法由openWithCompletionHandler的默认实现调用和saveToURL：forSaveOperation：completionHandler：分别在UIDocument对象遇到读取或写入错误时的方法。您可以通过通知用户来处理读取，保存和还原错误，如果情况允许，则尝试从错误中恢复。

请务必阅读contentsForType：error：方法的说明，以获取有关处理文档保存期间遇到的错误的指导。

3. Advanced Overrides

如果应用程序对读取或写入文档数据有特殊要求，它可以覆盖除loadFromContents:ofType:error:和contentsForType:error:之外的UIDocument方法。这些要求通常包括以下内容：

• 增量读取和写入大数据文件
  • 重写readFromURL：error：和writeContents：toURL：forSaveOperation：originalContentsURL：error方法。
• 文档数据的自定义表示（即，不是NSData或NSFileWrapper对象）
  • 覆盖readFromURL：error：方法（读取文档数据时）和writeContents：toURL：forSaveOperation：originalContentsURL：error：方法（写入文档数据时）。
• 在读取或写入数据之前或之后执行操作
  • 覆盖openWithCompletionHandler：和saveToURL：forSaveOperation：completionHandler：。
• 一种安全保存的自定义方法
  • 覆盖writeContents：andAttributes：safelyToURL：forSaveOperation：error：方法。
• 在保存之前更改文档的文件类型
  • 重写saveFileType方法以返回默认（fileType）以外的文件类型。一个例子是RTF文档，在用户向其添加图像之后，应该将其保存为RTFD文档。

如果覆盖大多数这些方法，请注意所有文档数据的读取和写入必须在后台队列上完成，并且必须与其他尝试读取和写入同一文档文件相协调。因此，您通常应该将超类实现（super）作为覆盖的一部分来调用，如果调用其他UIDocument方法，则通常应该在传入performAsynchronousFileAccessUsingBlock：方法调用的块中调用它们。阅读方法描述以获取详细信息。

4. Thread Safety Considerations

如果通过覆盖相关的访问器方法来覆盖任何文档属性属性（在 Accessing Document Attributes下列出），请注意UIKit框架可以在后台线程上调用这些访问器方法。 因此，您的重写实现必须是线程安全的。

---

Topics

1. Initializing a Document Object

• initWithFileURL:

返回使用其文件系统位置初始化的文档对象。

2. Accessing Document Attributes

• fileURL

  • 用于初始化文档的文件URL。

• localizedName

  • 文档的本地化名称。

• fileType

  • 文档的文件类型。

• fileModificationDate

  • 上次修改文档文件的日期和时间。

• documentState

  • 返回文档的当前状态。

• progress

  • 文档的上载或下载进度。

3. Writing Document Data

• closeWithCompletionHandler:

  • 保存任何更改后异步关闭文档。

• contentsForType:error:

  • 重写此方法以返回要保存的文档数据。

• saveToURL:forSaveOperation:completionHandler:

  • 将文档数据保存到应用程序沙箱中的指定位置。

• writeContents:andAttributes:safelyToURL:forSaveOperation:error:

  • 确保将文档数据安全地写入应用程序沙箱中的指定位置。

• writeContents:toURL:forSaveOperation:originalContentsURL:error:

  • 将文档数据写入由文件URL指示的沙箱位置的磁盘。

• savingFileType

  • 返回用于保存文档的文件类型。

• fileAttributesToWriteToURL:forSaveOperation:error:

  • 在写入或更新文档属性时，返回与文档文件关联的文件属性的字典。

• fileNameExtensionForType:saveOperation:

  • 返回一个文件扩展名，以附加到正在写入的文档文件的文件URL。

4. Reading Document Data

• openWithCompletionHandler:

  • 异步打开文档。

• loadFromContents:ofType:error:

  • 重写此方法以将文档数据加载到应用程序的数据模型中。

• readFromURL:error:

  • 在应用程序沙箱中指定位置的文件中读取文档数据。

5. Accessing Document Files Asynchronously

• performAsynchronousFileAccessUsingBlock:
  • 在并发后台队列上安排文档读取或文档写入操作。

6. Reverting a Document

• revertToContentsOfURL:completionHandler:
  • 将文档还原为存储在磁盘上的最新文档数据。

7. Disabling and Enabling Editing

• disableEditing

  • 重写以在对文档进行更改不安全时禁用编辑。

• enableEditing

  • 重写以在再次安全时进行编辑以对文档进行更改。

8. Tracking Changes and Autosaving

• hasUnsavedChanges

  • 返回文档是否有任何未保存的更改。

• updateChangeCount:

  • 通过指示更改类型来更新更改计数器。

• undoManager

  • 文档的撤消管理器。

• changeCountTokenForSaveOperation:

  • 重写以返回特定保存操作的更改标记。

• updateChangeCountWithToken:forSaveOperation:

  • 重写以参考UIKit传入的更改计数标记来更新更改计数。

• autosaveWithCompletionHandler:

  • 由UIKit调用以启动未保存更改的文档的自动保存。

9. Supporting User Activities

• userActivity

  • 封装此文档支持的用户活动的对象。

• restoreUserActivityState:

  • 恢复继续给定用户活动所需的状态。

• updateUserActivityState:

  • 更新给定用户活动的状态。

10. Resolving Conflicts and Handling Errors

• handleError:userInteractionPermitted:

  • 调用或覆盖以处理尝试读取，保存或还原文档期间发生的错误。

• finishedHandlingError:recovered:

  • 告诉UIKit你已经完成了错误的处理。

• userInteractionNoLongerPermittedForError:

  • 在没有立即处理错误的情况下继续安全的情况下发送。

11. Constants

• UIDocumentChangeKind

  • 用于指定文档更改类型的常量。

• UIDocumentSaveOperation

  • 用于指定保存操作类型的常量。

• UIDocumentState

  • 文件状态。

• NSUserActivityDocumentURLKey

  • 标识与用户活动关联的文档的密钥。

12. Notifications

• UIDocumentStateChangedNotification
  • 当文档状态发生变化时，由文档对象发布。

13. Conforms To

• NSFilePresenter, NSProgressReporting

后记

本篇主要讲述了UIDocument的数据存储，感兴趣的给个赞或者关注~~~