Contacts Framework

作者 dpearson26998d90fd121a26无许可证1.1K 个星标收录于 2026年10月8日更新于 2026年10月8日仓库2个月前更新

Read, create, update, and pick contacts using the Contacts and ContactsUI frameworks. Use when fetching contact data, saving new contacts, wrapping CNContactPickerViewController in SwiftUI, handling contact permissions, or working with CNContactStore fetch and save requests.

仅含说明Software Development
AI 生成的概览

指导 Swift 开发者使用 Contacts 和 ContactsUI 框架读取、创建、更新和选取联系人。

功能
该技能为在 Swift 6.3 / iOS 26+ 应用中使用 CNContactStore、CNSaveRequest 和 CNContactPickerViewController 提供参考指南和代码模式。内容涵盖授权状态、基于谓词和标识符的获取、键描述符、联系人的创建、更新与删除、SwiftUI 选择器封装、变更观察、常见错误以及审查清单。它产出的是文档和示例代码，而非可执行产物。
适用场景
适用于获取联系人数据、保存或更新联系人、在 SwiftUI 中封装 CNContactPickerViewController、处理联系人权限，或使用 CNContactStore 的获取与保存请求时。
运行要求
无需脚本，仅为说明和参考文档。假定使用 Swift 6.3 / iOS 26+ 开发环境以及 Contacts 和 ContactsUI 框架，并提及 Info.plist 键以及读取联系人备注所需的 Apple 审批权限。

Contacts Framework

Use CNContactStore, CNSaveRequest, and CNContactPickerViewController to fetch, create, update, or pick contacts in Swift 6.3 / iOS 26+ apps.

Contents

Setup

Project Configuration

  1. Add NSContactsUsageDescription to Info.plist explaining why the app accesses contacts. The app crashes if it uses contact data APIs without this key.
  2. No additional capability or entitlement is required for ordinary Contacts access.
  3. Add com.apple.developer.contacts.notes only when reading or writing CNContactNoteKey / CNContact.note; this entitlement requires Apple approval before public distribution.

Imports

swift
@preconcurrency import Contacts  // CNContactStore, CNSaveRequest, CNContactimport ContactsUI                // CNContactPickerViewController

Authorization

Request access before fetching or saving contacts. The picker (CNContactPickerViewController) does not require authorization -- the system grants access only to the contacts the user selects.

swift
let store = CNContactStore()
func requestAccess() async throws -> Bool {    return try await store.requestAccess(for: .contacts)}
// Check current status without promptingfunc checkStatus() -> CNAuthorizationStatus {    CNContactStore.authorizationStatus(for: .contacts)}

Authorization States

StatusMeaning
.notDeterminedUser has not been prompted yet
.authorizedFull read/write access granted
.deniedUser denied access; direct to Settings
.restrictedParental controls or MDM restrict access
.limitediOS 18+: user granted access to selected contacts only

Treat both .authorized and .limited as usable Contacts API states. With .limited, fetch, edit, and delete operations only apply to contacts the user granted or the app created. Use ContactAccessButton or contactAccessPicker(isPresented:completionHandler:) to let users add contacts to the app's limited-access set.

Fetching Contacts

Use unifiedContacts(matching:keysToFetch:) for predicate-based queries. Use enumerateContacts(with:usingBlock:) for batch enumeration of all contacts. For large cached address books, first fetch identifiers, then fetch detailed contacts in batches by identifier.

Fetch by Name

swift
func fetchContacts(named name: String) throws -> [CNContact] {    let predicate = CNContact.predicateForContacts(matchingName: name)    let keys: [CNKeyDescriptor] = [        CNContactGivenNameKey as CNKeyDescriptor,        CNContactFamilyNameKey as CNKeyDescriptor,        CNContactPhoneNumbersKey as CNKeyDescriptor    ]    return try store.unifiedContacts(matching: predicate, keysToFetch: keys)}

Fetch by Identifier

swift
func fetchContact(identifier: String) throws -> CNContact {    let keys: [CNKeyDescriptor] = [        CNContactGivenNameKey as CNKeyDescriptor,        CNContactFamilyNameKey as CNKeyDescriptor,        CNContactEmailAddressesKey as CNKeyDescriptor    ]    return try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)}

Enumerate All Contacts

Perform I/O-heavy enumeration off the main thread.

swift
func fetchAllContacts() throws -> [CNContact] {    let keys: [CNKeyDescriptor] = [        CNContactGivenNameKey as CNKeyDescriptor,        CNContactFamilyNameKey as CNKeyDescriptor    ]    let request = CNContactFetchRequest(keysToFetch: keys)    request.sortOrder = .givenName
    var contacts: [CNContact] = []    try store.enumerateContacts(with: request) { contact, _ in        contacts.append(contact)    }    return contacts}

Key Descriptors

Only fetch the properties you need. Accessing an unfetched property throws CNContactPropertyNotFetchedException.

Common Keys

KeyProperty
CNContactGivenNameKeyFirst name
CNContactFamilyNameKeyLast name
CNContactPhoneNumbersKeyPhone numbers array
CNContactEmailAddressesKeyEmail addresses array
CNContactPostalAddressesKeyMailing addresses array
CNContactImageDataKeyFull-resolution contact photo
CNContactThumbnailImageDataKeyThumbnail contact photo
CNContactBirthdayKeyBirthday date components
CNContactOrganizationNameKeyCompany name

Composite Key Descriptors

Use CNContactFormatter.descriptorForRequiredKeys(for:) to fetch all keys needed for formatting a contact's name.

swift
let nameKeys = CNContactFormatter.descriptorForRequiredKeys(for: .fullName)let keys: [CNKeyDescriptor] = [nameKeys, CNContactPhoneNumbersKey as CNKeyDescriptor]

Creating and Updating Contacts

Use CNMutableContact to build new contacts and CNSaveRequest to persist changes.

Creating a New Contact

swift
func createContact(givenName: String, familyName: String, phone: String) throws {    let contact = CNMutableContact()    contact.givenName = givenName    contact.familyName = familyName    contact.phoneNumbers = [        CNLabeledValue(            label: CNLabelPhoneNumberMobile,            value: CNPhoneNumber(stringValue: phone)        )    ]
    let saveRequest = CNSaveRequest()    saveRequest.add(contact, toContainerWithIdentifier: nil) // nil = default container    try store.execute(saveRequest)}

Updating an Existing Contact

You must fetch the contact with the properties you intend to modify, create a mutable copy, change the properties, then save.

swift
func updateContactEmail(identifier: String, email: String) throws {    let keys: [CNKeyDescriptor] = [        CNContactEmailAddressesKey as CNKeyDescriptor    ]    let contact = try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)    guard let mutable = contact.mutableCopy() as? CNMutableContact else { return }
    mutable.emailAddresses.append(        CNLabeledValue(label: CNLabelWork, value: email as NSString)    )
    let saveRequest = CNSaveRequest()    saveRequest.update(mutable)    try store.execute(saveRequest)}

Deleting a Contact

swift
func deleteContact(identifier: String) throws {    let keys: [CNKeyDescriptor] = [CNContactIdentifierKey as CNKeyDescriptor]    let contact = try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)    guard let mutable = contact.mutableCopy() as? CNMutableContact else { return }
    let saveRequest = CNSaveRequest()    saveRequest.delete(mutable)    try store.execute(saveRequest)}

Save Result and Recovery

try store.execute(saveRequest) returning without throwing is the save success checkpoint. Update an app-side cache or success UI only after that return. If it throws, surface or propagate the error, keep the unsaved intent available to the user, and correct the known cause—such as authorization, a read-only container, or invalid input—before building a fresh request. Serialize overlapping saves, do not access a request while execute(_:) is using it, and refetch a possibly stale contact before a corrected retry when access permits. Do not blindly repeat the same destructive request or require a universal read-back that the current access level may not permit. Load Extended Contacts Patterns [blocked] for multi-select, vCard, and optimized-search workflows.

Contact Picker

CNContactPickerViewController lets users pick contacts without granting full Contacts access. The app receives only the selected contact data.

SwiftUI Wrapper

swift
import SwiftUIimport ContactsUI
struct ContactPicker: UIViewControllerRepresentable {    @Binding var selectedContact: CNContact?
    func makeUIViewController(context: Context) -> CNContactPickerViewController {        let picker = CNContactPickerViewController()        picker.delegate = context.coordinator        return picker    }
    func updateUIViewController(_ uiViewController: CNContactPickerViewController, context: Context) {}
    func makeCoordinator() -> Coordinator {        Coordinator(self)    }
    final class Coordinator: NSObject, CNContactPickerDelegate {        let parent: ContactPicker
        init(_ parent: ContactPicker) {            self.parent = parent        }
        func contactPicker(_ picker: CNContactPickerViewController, didSelect contact: CNContact) {            parent.selectedContact = contact        }
        func contactPickerDidCancel(_ picker: CNContactPickerViewController) {            parent.selectedContact = nil        }    }}

Using the Picker

swift
struct ContactSelectionView: View {    @State private var selectedContact: CNContact?    @State private var showPicker = false
    var body: some View {        VStack {            if let contact = selectedContact {                Text("\(contact.givenName) \(contact.familyName)")            }            Button("Select Contact") {                showPicker = true            }        }        .sheet(isPresented: $showPicker) {            ContactPicker(selectedContact: $selectedContact)        }    }}

Filtering the Picker

Use predicates to control which contacts appear and what the user can select.

swift
let picker = CNContactPickerViewController()// Only show contacts that have an email addresspicker.predicateForEnablingContact = NSPredicate(format: "emailAddresses.@count > 0")// Selecting a contact returns it directly (no detail card)picker.predicateForSelectionOfContact = NSPredicate(value: true)

Observing Changes

Listen for external contact database changes to refresh cached data.

swift
func observeContactChanges() {    NotificationCenter.default.addObserver(        forName: .CNContactStoreDidChange,        object: nil,        queue: .main    ) { _ in        // Refetch contacts -- cached CNContact objects are stale        refreshContacts()    }}

Common Mistakes

DON'T: Fetch all keys when you only need a name

Over-fetching wastes memory and slows queries, especially for contacts with large photos.

swift
// WRONG: Fetches far more than the UI displays, including full-resolution photoslet keys: [CNKeyDescriptor] = [    CNContactFormatter.descriptorForRequiredKeys(for: .fullName),    CNContactImageDataKey as CNKeyDescriptor,    CNContactPhoneNumbersKey as CNKeyDescriptor,    CNContactEmailAddressesKey as CNKeyDescriptor,    CNContactPostalAddressesKey as CNKeyDescriptor,    CNContactBirthdayKey as CNKeyDescriptor]
// CORRECT: Fetch only what you displaylet keys: [CNKeyDescriptor] = [    CNContactGivenNameKey as CNKeyDescriptor,    CNContactFamilyNameKey as CNKeyDescriptor]

DON'T: Access unfetched properties

Accessing a property that was not in keysToFetch throws CNContactPropertyNotFetchedException at runtime.

swift
// WRONG: Only fetched name keys, now accessing phonelet keys: [CNKeyDescriptor] = [CNContactGivenNameKey as CNKeyDescriptor]let contact = try store.unifiedContact(withIdentifier: id, keysToFetch: keys)let phone = contact.phoneNumbers.first // CRASH
// CORRECT: Include the key you needlet keys: [CNKeyDescriptor] = [    CNContactGivenNameKey as CNKeyDescriptor,    CNContactPhoneNumbersKey as CNKeyDescriptor]

DON'T: Mutate a CNContact directly

CNContact is immutable. You must call mutableCopy() to get a CNMutableContact.

swift
// WRONG: CNContact has no setterlet contact = try store.unifiedContact(withIdentifier: id, keysToFetch: keys)contact.givenName = "New Name" // Compile error
// CORRECT: Create mutable copyguard let mutable = contact.mutableCopy() as? CNMutableContact else { return }mutable.givenName = "New Name"

DON'T: Skip authorization and assume access

Do not let fetch or save calls be the first place the user sees authorization. If status is .notDetermined, request access; if access was denied, contact operations fail with an authorization error.

swift
// WRONG: Jump straight to fetchlet contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keys)
// CORRECT: Check or request access firstlet granted = try await store.requestAccess(for: .contacts)guard granted else { return }let contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keys)

DON'T: Run heavy fetches on the main thread

enumerateContacts performs I/O. Running it on the main thread blocks the UI. When strict concurrency checks complain about CNContact crossing task or actor boundaries, use @preconcurrency import Contacts in that file or map contacts into Sendable view models before returning them.

swift
// WRONG: Main thread enumerationfunc loadContacts() {    try store.enumerateContacts(with: request) { contact, _ in ... }}
// CORRECT: Run on a background threadfunc loadContacts() async throws -> [CNContact] {    try await Task.detached {        var results: [CNContact] = []        try store.enumerateContacts(with: request) { contact, _ in            results.append(contact)        }        return results    }.value}

Review Checklist

  • NSContactsUsageDescription added to Info.plist
  • requestAccess(for: .contacts) called before fetch or save operations
  • .limited treated as usable access with selected-contact caveats
  • ContactAccessButton or contactAccessPicker offered when users need to expand limited access
  • Authorization denial handled gracefully (guide user to Settings)
  • Only needed CNKeyDescriptor keys included in fetch requests
  • CNContactFormatter.descriptorForRequiredKeys(for:) used when formatting names
  • Mutable copy created via mutableCopy() before modifying contacts
  • Every create/update/delete uses CNSaveRequest; app state advances only after execute(_:) succeeds, and failures are surfaced before a corrected request is constructed
  • Heavy fetches (enumerateContacts) run off the main thread
  • CNContactStoreDidChange observed to refresh cached contacts
  • CNContactPickerViewController used when full Contacts access is unnecessary
  • Picker predicates set before presenting the picker view controller
  • Single CNContactStore instance reused across the app

References

来源与署名

来源：dpearson2699/swift-ios-skills位于skills/contacts-framework提交8d90fd1

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 dpearson2699/swift-ios-skills 的技能

Widgetkit

dpearson2699

指导实现、审查和改进 iOS、iPadOS、watchOS 与 CarPlay 上的 WidgetKit 小组件和控制项。

Software Development1.1K2个月前更新

Weatherkit

dpearson2699

指导 iOS 开发者使用 WeatherService 获取 WeatherKit 预报、警报与署名信息。

Software Development1.1K2个月前更新

Vision Framework

dpearson2699

Implement computer vision features including text recognition (OCR), face detection, barcode scanning, image segmentation, object tracking, and document scanning in iOS apps. Covers both the modern Swift-native Vision API (iOS 18+) and legacy VNRequest patterns, VisionKit DataScannerViewController for live camera scanning, and CoreMLRequest/VNCoreMLRequest for custom model inference. Use when adding OCR, barcode scanning, face detection, or custom Core ML model inference with Vision.

待分类1.1K2个月前更新

Tipkit

dpearson2699

Implement and review Apple TipKit feature-discovery UI for iOS 17+ apps. Use when adding or auditing in-app tips, contextual help, coach marks, Tip, TipView, popoverTip, rules, events, actions, display frequency, testing overrides, reusable tip identifiers, or iOS 18+ TipGroup and CloudKit tip sync; avoid for generic SwiftUI navigation or layout outside tip presentation.

待分类1.1K2个月前更新

Tabletopkit

dpearson2699

指导使用 TabletopKit 在 visionOS 上构建多人空间桌游，涵盖棋具、座位、动作与 RealityKit 渲染。

Software Development1.1K2个月前更新

Swiftui Webkit

dpearson2699

指导在 iOS 26 及更高版本的 SwiftUI 应用中使用 WebKit for SwiftUI 嵌入和控制网页内容。

Software Development1.1K2个月前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精选

依据从远程来源获取的 Web Interface Guidelines 审查 UI 代码，并以 file:line 形式报告问题。

Software Development32K5周前更新

Vercel React Native Skills

vercel-labs

精选

React Native 与 Expo 最佳实践规则，涵盖列表性能、动画、导航、UI 模式、状态与 monorepo 配置。

Software Development32K5周前更新

Vercel React Best Practices

vercel-labs

精选

Vercel 的 React 与 Next.js 性能指南，以 70 条规则的形式用于编写、审查和重构代码。

Software Development32K5周前更新