Contacts Swift 完全指南：方法与实战教程

1. 什么是 Contacts 框架？为什么需要它？

Contacts 框架（Contacts.framework）是 Apple 官方提供的 API，用于在 iOS、macOS、watchOS 和 tvOS 设备上管理通讯录（联系人）。它取代了老旧的 AddressBook 框架，提供了现代化、面向对象的接口来访问用户联系人。该框架的核心任务是统一读取、创建、更新和删除联系人的流程，并支持联系人分组管理。

为什么需要它？任何需要与通讯录交互的应用（如即时通讯工具、CRM 系统、拨号应用、社交网络）都必须使用 Contacts 框架。它允许安全地请求用户权限，高效加载大量数据（通过分页加载和谓词过滤），并支持统一联系人（例如，将来自 iCloud 和 Google 的同一联系人合并）。

与旧方案不同，Contacts 完全支持 Swift（包括 async/await），以 CNContactStore 作为统一入口，并提供不可变对象用于读取、可变对象用于写入，使代码更安全、更可预测。

2. 安装指南

Contacts 框架是 Apple 系统框架的一部分。你无需通过 CocoaPods、SPM 或 Carthage 等包管理器安装——它已内置于设备中。只需在代码中导入模块即可使用。

重要提示： 使用联系人功能前，必须在项目的 Info.plist 文件中添加 NSContactsUsageDescription 键。否则，尝试访问存储时应用会崩溃。

命令（无需执行，仅作说明）：

由于这是系统框架，不存在 pip、npm 或 cargo 命令。只需在 Swift 文件中添加导入：

import Contacts

3. 快速入门——最小可用示例

以下示例请求访问通讯录权限，并在控制台输出所有联系人的姓名。

import Contacts
import UIKit

// 1. 创建存储实例
let store = CNContactStore()

// 2. 请求权限
store.requestAccess(for: .contacts) { granted, error in
    guard granted else {
        print("访问被拒绝：\(error?.localizedDescription ?? "未知错误")")
        return
    }
    
    // 3. 创建查询请求
    let keysToFetch = [CNContactGivenNameKey, CNContactFamilyNameKey]
    let request = CNContactFetchRequest(keysToFetch: keysToFetch)
    
    // 4. 执行查询
    do {
        try store.enumerateContacts(with: request) { contact, stopPointer in
            print("找到联系人：\(contact.givenName) \(contact.familyName)")
        }
    } catch {
        print("获取联系人时出错：\(error.localizedDescription)")
    }
}

4. 核心方法/函数/类

4.1. CNContactStore

签名： class CNContactStore : NSObject

功能： 访问联系人数据库的核心类。所有操作（查询、保存、删除）都通过它执行。

示例：

let store = CNContactStore()
// 后续所有操作都使用 store

4.2. requestAccess(for:completionHandler:)

签名： func requestAccess(for entityType: CNEntityType, completionHandler: @escaping (Bool, Error?) -> Void)

功能： 请求用户授权访问指定实体类型（如联系人）。首次调用会弹出系统权限对话框。