File Provider Extension：它是什么以及 iOS 文件提供程序如何工作

什么是 iOS 中的 File Provider Extension

File Provider Extension 是一个应用扩展，向文件应用添加新的文档来源。云服务 — Google Drive、Dropbox、OneDrive 或企业存储 — 可以直接在系统界面中显示其文件结构，无需打开单独的应用程序。

用户操作远程文件的方式与设备上保存的文件完全相同：浏览文件夹内容、拖动文档、在任何兼容应用中打开它们并将修改保存回云端。根据 WWDC 2025，File Provider Extension 支持最多 1000 个同时同步操作，并通过动态优先级管理适应网络速度。

扩展在后台运行 — iOS 在需要同步时启动它，并可以在资源不足时强制终止它。所有操作必须是幂等的，并支持从检查点恢复。

架构和文件同步机制

File Provider Extension 具有三层架构：系统进程 Files.app、提供程序扩展和远程服务器。系统向扩展请求数据，扩展将请求转换为云服务的 API 调用，并通过 NSFileProviderItem 返回结果。

增量同步

每次更新时，扩展不会加载完整的文件结构，而是仅传输 已修改的元素。NSFileProviderManager 提供了用于发送增量更新的方法 — “文件 A 已添加”，“文件 B 已修改”，“文件夹 C 已删除”。这大幅减少了流量，并加快了变更的显示。

根据 Apple Engineering，增量同步将传输数据量减少了 60–80%，与完全重新加载相比。建议使用 NSFileProviderSyncAnchor 来标记同步状态并最小化重复请求。

设备上的缓存

File Provider Extension 可以将文件本地缓存以便离线访问。打开文件时，系统向扩展发送请求，扩展决定 — 从服务器下载内容还是返回已缓存的版本。NSFileProviderItem 通过 isDownloaded 和 isUploaded 字段指示缓存级别。

Apple 建议根据文件大小配置缓存策略：图片和文档 — 完全缓存，视频 — 仅预览，归档 — 用户请求时。

NSFileProviderManager：管理文件提供程序

NSFileProviderManager 是扩展与系统通信的中心类。它提供了用于向系统通知变更、创建新元素、管理下载和处理错误的方法。每个 NSFileProviderManager 实例都绑定到特定的域。

关键方法

signalEnumerator(for:) — 通知系统文件夹内容已变更，需要重新读取列表。reimportItem(_:) — 在服务器变更后重新导入指定元素。registerURLSessionTask:forItemWithIdentifier: — 将后台下载绑定到特定文件以跟踪进度。

重要限制：NSFileProviderManager 仅在扩展进程中工作。主应用无法直接调用其方法来管理文件结构 — 同步必须由扩展或系统发起。

let manager = NSFileProviderManager.default()
manager.signalEnumerator(for: workingSet) { error in
    if let error = error {
        print("Signal failed: \(error)")
    }
}

管理下载

为了在后台下载文件，NSFileProviderManager 使用具有后台配置的 URLSession。扩展创建下载任务并在管理器中注册它，管理器将其绑定到相应的元素。系统根据用户活动自动跟踪下载进度和优先级。

实现 File Provider Extension

创建 File Provider Extension 从在 Xcode 中添加新的 target 开始，使用 File Provider Extension 模板。Xcode 自动生成一个继承自 NSFileProviderExtension 的类和最小方法集，用于与元素工作。

NSFileProviderItem 和元数据

文件结构的每个元素 — 文件或文件夹 — 实现 NSFileProviderItem 协议。该协议定义了必要字段：itemIdentifier、parentItemIdentifier、filename、typeIdentifier 和 capabilities。可选地可以指定大小、修改日期和下载标志。

struct CloudItem: NSFileProviderItem {
    let itemIdentifier: NSFileProviderItemIdentifier
    let parentItemIdentifier: NSFileProviderItemIdentifier
    let filename: String
    let typeIdentifier: String
    let capabilities: NSFileProviderItemCapabilities
    let documentSize: NSNumber?
}

处理枚举请求

enumerator(for:) 方法返回一个实现 NSFileProviderEnumerator 的对象，该对象应系统请求提供文件夹内容。iOS 可以请求枚举根文件夹、子文件夹和工作集 — 后者用于显示最近或收藏的文件。

Apple 建议使用异步枚举方法，通过 NSFileProviderPage 进行分页，以避免同时加载数千个元素。每页 50–100 个元素对性能最佳。

域和多账户架构

NSFileProviderDomain 是在一个扩展内区分不同账户的机制。如果用户在应用中授权了多个账户 — 个人和企业 Google Drive — 每个账户创建一个单独的域，在文件应用中显示为单独的来源。

每个域拥有唯一标识符、显示名称和状态。用户可以临时禁用或删除域，不会影响其他账户。系统为每个活动域启动单独的扩展进程，确保账户之间的数据隔离。

根据 Apple 的建议，每个扩展不应创建超过 10 个域 — 过多的数量会减慢文件应用的启动速度并增加内存消耗。对于拥有大量账户的服务，最好将它们聚合到一个域中，在扩展内切换配置文件。

let domain = NSFileProviderDomain(
    identifier: "work",
    displayName: "Corporate Drive"
)
NSFileProviderManager.add(domain) { error in
    if let error = error {
        print("Failed to add domain: \(error)")
    }
}