SuperAPI AI 工具集

contacts-framework

通用与其它

查看项目

更新于 10-16 05:52

技能介绍

用途:在 iOS 应用中访问系统通讯录,读取、创建、更新联系人,或让用户自行选择联系人。主要能力:CNContactStore 读取或写入已授权联系人;CNSaveRequest 创建、更新、删除;CNContactPickerViewController 让用户选择而不需广泛权限;iOS 18+ 的 ContactAccessButton/contactAccessPicker 扩展受限访问;CNContactVCardSerialization 支持 vCard 导入导出。

使用方式:直接访问 API 前需在 Info.plist 添加 NSContactsUsageDescription,缺失会导致终止;普通访问无需 entitlement,读写 CNContact.note 需 Apple 批准的 com.apple.developer.contacts.notes。抓取时只请求将访问的键,读取未抓取属性会抛 CNContactPropertyNotFetchedException;用 unifiedContacts 做谓词查询,用 enumerateContacts 遍历,先取标识符再分批补齐大缓存。变更用 CNMutableContact 和 CNSaveRequest,store.execute(request) 不抛错即为成功边界,成功后再更新状态;失败时保留用户意图,不要盲目重放破坏性请求。

并发与限制:枚举属 I/O 密集操作,应在主 actor 之外执行;严格并发下在框架边界用 @preconcurrency import Contacts,或映射为自有 Sendable 模型再跨 actor。需监听 CNContactStoreDidChange 并失效缓存重取,复用单个长期 store。须显式处理 .notDetermined、.authorized、.limited、.denied、.restricted 各授权状态。常见错误包括无必要地请求全量权限、把 .limited 当拒绝、抓取全部键或全分辨率图片等。