# iCloud 驱动器参考 **目的**：使用无处不在的容器进行基于文件的 iCloud 同步的综合参考 **可用性**：iOS 5.0+（基本）、iOS 8.0+（iCloud Drive）、iOS 11.0+（现代 API）**上下文**：基于文件的云存储，而不是数据库（使用 CloudKit 存储结构化数据） ## 何时使用此技能在以下情况下使用此技能： * 实现基于文档的iCloud同步 * 跨设备同步用户文件 * 构建基于文档的应用程序（如 Pages、Numbers） * 协调跨进程的文件访问 * 处理iCloud文件冲突 * 使用 NSUbiquitousKeyValueStore 进行首选项 **不适用于**：具有关系的结构化数据（使用 `axiom-cloudkit-ref` 代替） ** ** ## 概述 **iCloud Drive 用于基于文件的同步**，而不是结构化数据。 **使用时**： * 用户创建/编辑文档 * 文件需要像 Dropbox 一样同步 * 文档选择器集成 **当**时不要使用： * 需要可查询的结构化数据（使用CloudKit） * 需要记录之间的关系（使用CloudKit） * 小键值偏好（使用 NSUbiquitousKeyValueStore） ** ** ## 无处不在的容器 ### 获取无处不在的容器 URL // ✅ 正确：获取 iCloud 容器 func getICloudContainerURL() -> URL？ { // nil = 使用权利中的第一个容器返回 FileManager.default.url( 对于UbiquityContainerIdentifier：nil ） } // ✅ 检查 iCloud 是否可用如果让 iCloudURL = getICloudContainerURL() { print("iCloud 可用: \(iCloudURL)") } 否则{ print("iCloud 不可用（未登录或无权利）") } ### 容器结构 iCloud 容器/ ├── Documents/ # 用户可见的文件（文件应用） │ └── MyApp/ # 你的应用程序的文档 ├── 图书馆/ # 对用户隐藏 │ ├── 应用支持/ │ └── 缓存/ ### 保存到 iCloud Drive // ✅ 正确：将文档保存到 iCloud func saveToICloud(数据：数据，文件名：字符串) throws { Guard 让 iCloudURL = FileManager.default.url( 对于UbiquityContainerIdentifier：nil ）否则{ 抛出 iCloudError.notAvailable } 让 DocumentsURL = iCloudURL.appendingPathComponent("文档") // 如果需要创建目录尝试 FileManager.default.createDirectory( 位于：文档URL， withIntermediateDirectories: true ）让 fileURL = filesURL.appendingPathComponent(文件名) // 使用文件协调来安全访问让协调器 = NSFileCoordinator() var 错误：NSError？协调员.坐标( writingItemAt：文件URL，选项：.for替换，错误：&错误 ) { 新网址试试？ data.write（至：newURL） } 如果让错误=错误{ 抛出错误 } } ** ** ## 文件协调（对于安全至关重要） **访问 iCloud 文件时始终使用 NSFileCoordinator**。这可以防止： * 具有同步的竞争条件 * 数据损坏 * 丢失更新 ### 读取文件 // ✅ 正确：协调读取 func readICloudFile(url: URL) 抛出 -> 数据 { 让协调器 = NSFileCoordinator() var 数据：数据？ var协调错误：NSError？协调员.坐标（阅读项目在：网址，选项：[]，错误：&协调错误 ) { 新网址数据=尝试？数据（内容：newURL） } 如果让错误=协调错误{ 抛出错误 } 保护让数据=数据其他{ 抛出 fileError.readFailed } 返回数据 } ### 写入文件 // ✅ 正确：协调写入 func writeICloudFile(data: Data, to url: URL) throws { 让协调器 = NSFileCoordinator() var协调错误：NSError？协调员.坐标（写作项目：网址，选项：.for替换，错误：&协调错误 ) { 新网址试试？ data.write（至：newURL） } 如果让错误=协调错误{ 抛出错误 } } ### 移动文件 // ✅ 正确：协调移动 func moveFile(从 sourceURL: URL, 到 destURL: URL) throws { 让协调器 = NSFileCoordinator() var协调错误：NSError？协调员.坐标（ writingItemAt：源URL，选项：.forMoving， writingItemAt：destURL，选项：.for替换，错误：&协调错误 ) { 新源, 新目标试试？ FileManager.default.moveItem（位于：newSource，至：newDest） } 如果让错误=协调错误{ 抛出错误 } } ** ** ## iCloud 的 URL 资源值 ### 检查 iCloud 状态 // ✅ 检查文件是否在 iCloud 中 func isInICloud(url: URL) -> Bool { 让值=尝试？ url.resourceValues(forKeys: [.isUbiquitousItemKey]) 返回值？.isUbiquitousItem ??假的 } // ✅ 检查下载状态 func getDownloadStatus(url: URL) -> 字符串 { 让值=尝试？ url.resourceValues(forKeys: [ .ubiquitousItemDownloadingStatusKey， .ubiquitousItemIsDownloadingKey， .ubiquitousItemDownloadingErrorKey ]）如果让下载=值？.ubiquitousItemIsDownloading，下载{ 返回“正在下载...” } 如果让状态=值？.ubiquitousItemDownloadingStatus { 开关状态{ 案例.当前：返回“已下载” 案例.notDownloaded: 返回“未下载（仅限 iCloud）” 案例.下载：返回“已下载” @未知默认值：返回“未知” } } 返回“未知” } // ✅ 检查上传状态 func isUploading(url: URL) -> Bool { 让值=尝试？ url.resourceValues(forKeys: [.ubiquitousItemIsUploadingKey]) 返回值？.ubiquitousItemIsUploading ??假的 } // ✅ 检查冲突 func hasConflicts(url: URL) -> Bool { 让值=尝试？ url.resourceValues(forKeys: [ .ubiquitousItemHasUnresolvedConflictsKey ]）返回值？.ubiquitousItemHasUnresolvedConflicts ??假的 } ### 下载文件 // ✅ 正确：请求下载 func downloadFromICloud(url: URL) throws { 尝试 FileManager.default.startDownloadingUbiquitousItem(at: url) } // ✅ 监控下载进度让查询 = NSMetadataQuery() query.predicate = NSPredicate(格式: "%K == %@", NSMetadataItemURLKey，url 为 NSURL) query.searchScopes = [NSMetadataQueryUbiquitousDataScope] 通知中心.default.addObserver( forName: .NSMetadataQueryDidUpdate, 对象：查询，队列：.main ) { 通知中 // 检查进度如果让 item = query.results.first 为？ NSMetadataItem { 如果让百分比 = item.value(forAttribute: NSMetadataUbiquitousItemPercentDownloadedKey) 作为？双{ print("已下载：\(百分比)%") } } } 查询.start() ** ** ## 冲突解决 ### 检测冲突 // ✅ 获取冲突版本 func getConflictVersions(for url: URL) -> [NSFileVersion]? { 返回 NSFileVersion.unresolvedConflictVersionsOfItem(at: url) } ### 解决冲突 // ✅ 正确：解决冲突 func resolveConflicts(at url: URL,keepingVersion: ConflictResolution) throws { 保护让冲突= NSFileVersion.unresolvedConflictVersionsOfItem（at：url）， !conflicts.isEmpty else { return // 没有冲突 } 让当前 = 尝试 NSFileVersion.currentVersionOfItem(at: url) 切换保持版本 { 案例.当前： // 保留当前版本，丢弃其他版本对于冲突中的冲突{ 冲突.isResolved = true } case .other(让 selectedVersion): // 用选择的冲突版本替换当前版本尝试 selectedVersion.replaceItem(at: url, options: []) selectedVersion.isResolved = true // 将其他冲突标记为已解决对于冲突中的冲突，其中冲突！= selectedVersion { 冲突.isResolved = true } 案例.手册： // 应用程序手动合并，然后标记已解决让 mergedData = mergeConflicts(当前：当前，冲突：冲突) 尝试 mergedData.write(to: url) 对于冲突中的冲突{ 冲突.isResolved = true } } // 删除已解析的版本尝试 NSFileVersion.removeOtherVersionsOfItem(at: url) } 枚举冲突解决方案{ 情况电流案例其他（NSFileVersion）案例手册 } ** ** ## NSUbiquitousKeyValueStore（首选项同步） **仅适用于较小的首选项**（总计 <1 MB，<1024 个键） // ✅ 正确：同步小首选项让 store = NSUbiquitousKeyValueStore.default // 设置值 store.set(true, forKey: "darkModeEnabled") store.set(2.0, forKey: "textSizeMultiplier") store.set(["en", "es"], forKey: "selectedLanguages") // 同步存储.synchronize() // 读取值让 darkMode = store.bool(forKey: "darkModeEnabled") 让 textSize = store.double(forKey: "textSizeMultiplier") // 监听其他设备的变化通知中心.default.addObserver( forName: NSUbiquitousKeyValueStore.didChangeExternallyNotification, 对象：商店，队列：.main ) { 通知中 // 使用新值更新 UI 更新首选项() } **限制**： * 总存储空间：1 MB * 最大按键数：1024 * 最大值大小：1 MB * 仅用于偏好，不用于数据 ** ** ## 权利 com.apple.developer.icloud-services <数组> 云文档 com.apple.developer.ubiquity-container-identifiers <数组> iCloud.com.example.app com.apple.developer.ubiquity-kvstore-identifier <字符串>$(TeamIdentifierPrefix)com.example.app ** ** ## 常见模式 ### 模式 1：文档选择器集成 // ✅ 显示 iCloud 文档选择器导入统一类型标识符让选择器 = UIDocumentPickerViewController( forOpeningContentTypes：[.pdf、.plainText] ）选择器.delegate = self picker.allowsMultipleSelection = false // 启用 iCloud picker.directoryURL = getICloudContainerURL() 存在（选择器，动画：true） ### 模式 2：监视目录的更改 // ✅ 监控 iCloud 目录类 ICloudMonitor { 让查询 = NSMetadataQuery() func startMonitoring(目录: URL) { query.predicate = NSPredicate(格式: "%K BEGINSWITH %@", NSMetadataItemPathKey，目录.path） query.searchScopes = [NSMetadataQueryUbiquitousDataScope] 通知中心.default.addObserver( forName: .NSMetadataQueryDidUpdate, 对象：查询，队列：.main ) { [弱自我] _ in self?.processResults() } 查询.start() } func 处理结果() { 对于 query.results 中的项目 { 如果让metadataItem = item as？ NS元数据项，让 url =metadataItem.value(forAttribute: NSMetadataItemURLKey) 作为？网址{ print("文件：\(url.lastPathComponent)") } } } } ** ** ## 快速参考任务|应用程序接口 |注释 ---|---|--- 获取 iCloud URL | `FileManager.default.url(forUbiquityContainerIdentifier:)` |如果不可用则返回 nil 检查是否在 iCloud | `.isUbiquitousItemKey` 资源值 |布尔下载文件 | `startDownloadingUbiquitousItem(at:)` |异步，使用 NSMetadataQuery 进行监控检查下载状态 | `.ubiquitousItemDownloadingStatusKey` |当前/未下载/已下载检查冲突 | `.ubiquitousItemHasUnresolvedConflictsKey` |布尔解决冲突 | `NSFileVersion.unresolvedConflictVersionsOfItem(at:)` |手动合并或选择版本同步偏好设置 | `NSUbiquitousKeyValueStore.default` |总计 <1 MB 文件协调 | `NSFileCoordinator` | **始终**用于 iCloud 文件 ** ** ## 相关技能 * `axiom-storage` — 选择 iCloud Drive 与 CloudKit * `axiom-cloudkit-ref` — 用于结构化数据同步 * `axiom-cloud-sync-diag` — 调试 iCloud 同步问题 ** ** **最后更新**：2025-12-12 **技能类型**：参考 **最低 iOS**：5.0（基本）、8.0（iCloud Drive）、11.0（现代 API）

Axiom Icloud 驱动器参考

包含技能