UIDocumentPickerViewController — iOS 文档操作

什么是 UIDocumentPickerViewController？

UIDocumentPickerViewController 是一个 UIKit 控制器，提供用于选择文档的系统界面。它是 UIKit 框架的一部分，自 iOS 8 起可用。该控制器显示一个文件浏览器，包括本地存储、iCloud Drive 和已注册的第三方云服务。

该控制器异步工作：调用 present 后，用户会看到系统对话框，选择文件，结果通过委托返回。应用程序无需特殊权限即可访问所选文件 — 系统选择器自动提供对 URI 的临时访问。

UIDocumentPickerViewController 通过 UIPopoverPresentationController 支持 iPad，并为 iPhone 提供自适应界面。从 iOS 14 开始，该控制器获得了更新的设计和对 iPadOS 中侧边栏导航的支持。

工作模式：import 和 export

UIDocumentPickerViewController 以两种主要模式工作，每种模式决定了应用程序如何访问文件。模式通过 forOpeningContentTypes 或 forExporting 参数根据任务设置。

Import 模式 (forOpeningContentTypes) 将所选文件复制到应用程序沙盒中。应用程序收到其自己的文件副本的 URL，该副本仅对其可访问。这是一种安全模式：其他应用程序的文件不会被修改，副本完全由当前应用程序控制。

Export 模式 (forExporting) 不复制文件，而是提供原始文件的 URL。应用程序可以通过链接读取文件，但更改不会保存回去。当需要将文件传输到另一个应用程序或通过电子邮件发送时，使用此模式。要写入更改，使用 open 模式配合 security-scoped URL。

配置选择器和按 UTI 过滤

UTI（统一类型标识符） 是 Apple 生态系统中内容类型的识别系统。UIDocumentPickerViewController 根据通过 forOpeningContentTypes 传递的 UTI 数组过滤显示的文件。如果未指定 UTI，选择器将显示所有文件类型。

• PDF — com.adobe.pdf。选择器仅显示 PDF 文档。
• 图片 — public.image。包括 JPEG、PNG、HEIC 和其他格式。
• 文本 — public.plain-text。显示 .txt、.csv 和其他文本文件。
• 音频 — public.audio。包括 MP3、AAC、WAV 和无损格式。
• 视频 — public.movie。显示 MP4、MOV、AVI 和其他视频格式。

要选择多种类型，传递数组 [UTType.pdf, UTType.image]。从 iOS 14 开始，Apple 建议使用 UTType 而不是字符串常量。当所选提供程序更改时，UIDocumentPickerViewController 会自动更新显示的类型列表。

代码示例：在 Swift 中选择文档

实现 UIDocumentPickerViewController 在 Swift 中非常简单：使用 UTI 类型创建控制器实例，设置委托并调用 present。选择文件后，委托在 didPickDocumentsAt 方法中接收 URL 数组。每个 URL 都是 security-scoped 链接，需要调用 startAccessingSecurityScopedResource。

let picker = UIDocumentPickerViewController(
    forOpeningContentTypes: [.pdf, .image],
    asCopy: true
)
picker.delegate = self
picker.allowsMultipleSelection = false
present(picker, animated: true)

// MARK: - UIDocumentPickerDelegate
func documentPicker(
    _ controller: UIDocumentPickerViewController,
    didPickDocumentsAt urls: [URL]
) {
    guard let url = urls.first else { return }
    url.startAccessingSecurityScopedResource()
    defer { url.stopAccessingSecurityScopedResource() }
    // 从 url 读取文件
}

Security-scoped 资源

Security-scoped URL 需要在读取前调用 startAccessingSecurityScopedResource。该方法通知系统应用程序正在获取沙盒外部文件的临时访问权限。完成后务必调用 stopAccessingSecurityScopedResource，否则系统可能会阻止访问。

UIDocumentPickerDelegate 和结果处理

UIDocumentPickerDelegate 通过两个方法接收文件选择结果：成功时的 didPickDocumentsAt 和取消时的 didPickDocumentsAt。如果用户未选择就关闭了选择器，iOS 会自动调用取消方法。

错误处理包括检查 URL 的可用性。如果用户从 iCloud Drive 选择了文件但设备离线，URL 可能不可用。建议在读取前检查 FileManager.default.isReadableFile，并向用户显示可理解的错误消息。

对于 iOS 14+，新的 documentPicker:didPickDocumentsAt 方法（带 URL 数组）可用。旧的 didPickDocumentAt（单个）方法已弃用。始终处理数组，即使 allowsMultipleSelection 被禁用 — Apple 建议使用统一的处理程序。

在 iPad 上的 UIDocumentPickerViewController

iPad 需要 UIDocumentPickerViewController 的特殊配置。在 iPad 上，选择器显示为弹出窗口，需要指定 sourceView 以正确定位。没有 sourceView，控制器可能会在 iPadOS 上崩溃并出现异常。

对于弹出窗口，使用 popoverPresentationController 属性。指定 sourceView 和 sourceRect 以锚定到按钮或表格单元格。在 iPhone 上，此代码没有效果 — iOS 会自动全屏显示选择器。从 iPadOS 16 开始，控制器支持侧边栏和分屏视图以获得更好的导航体验。

UIDocumentPickerViewController 的自适应设计会自动在 full-screen（iPhone）和 popover（iPad）之间切换。开发人员无需为不同设备实现单独的控制器 — 只需为 iPad 正确配置 popoverPresentationController 即可。