axiom-contacts-ref（Axiom 联系人参考）

Contacts API Reference

Overview

The Contacts framework provides programmatic access to the system contact database. ContactsUI provides system view controllers for contact selection and display. ContactProvider enables apps to expose their own contacts to the system.

Platform: iOS 9.0+, iPadOS 9.0+, macOS 10.11+, Mac Catalyst 13.1+, watchOS 2.0+, visionOS 1.0+

Part 1: CNContactStore

The primary gateway for contact data. "Fetch methods perform I/O — avoid using the main thread."

Authorization

// Check status (static method)
let status = CNContactStore.authorizationStatus(for: .contacts)
// Returns: .notDetermined, .restricted, .denied, .authorized, .limited (iOS 18+)

// Request access
let store = CNContactStore()
try await store.requestAccess(for: .contacts)  // Returns Bool

Info.plist required: NSContactsUsageDescription (crash without it).

Special entitlement: com.apple.developer.contacts.notes — required to read/write note field. Requires Apple approval.

Fetching Contacts

// Single contact by identifier
let contact = try store.unifiedContact(
    withIdentifier: identifier,
    keysToFetch: keys
)

// Search by predicate
let contacts = try store.unifiedContacts(
    matching: predicate,
    keysToFetch: keys
)

// Current user's card
let me = try store.unifiedMeContact(withKeysToFetch: keys)

// Memory-efficient enumeration
let request = CNContactFetchRequest(keysToFetch: keys)
request.predicate = predicate  // Optional filter
request.sortOrder = .userDefault  // .none, .givenName, .familyName, .userDefault
try store.enumerateContacts(with: request) { contact, stop in
    // stop.pointee = true to break early
}

Built-in Predicates

CNContact.predicateForContacts(matchingName: "John")
CNContact.predicateForContacts(matchingEmailAddress: "john@example.com")
CNContact.predicateForContacts(matching: CNPhoneNumber(stringValue: "+1555..."))
CNContact.predicateForContacts(withIdentifiers: [id1, id2])
CNContact.predicateForContactsInGroup(withIdentifier: groupId)
CNContact.predicateForContactsInContainer(withIdentifier: containerId)

Containers and Groups

store.containers(matching: predicate)     // [CNContainer]
store.groups(matching: predicate)         // [CNGroup]
store.defaultContainerIdentifier          // String (property, not method)

CNContainer types: .local, .exchange, .cardDAV, .unassigned

Change Tracking

store.currentHistoryToken  // Data? — save for incremental sync

Change Notification

NotificationCenter.default.addObserver(
    forName: .CNContactStoreDidChange, object: nil, queue: .main
) { _ in
    // Refetch visible contacts
}

Save Operations

let saveRequest = CNSaveRequest()
saveRequest.add(contact, toContainerWithIdentifier: nil)  // nil = default
saveRequest.update(contact)
saveRequest.delete(contact.mutableCopy() as! CNMutableContact)
try store.execute(saveRequest)

Part 2: CNContact Key Descriptors

You MUST specify which properties to fetch. Accessing an unfetched property throws CNContactPropertyNotFetchedException.

Common Key Constants

Convenience Descriptors

// All keys needed for name display (locale-aware)
CNContactFormatter.descriptorForRequiredKeys(for: .fullName)
CNContactFormatter.descriptorForRequiredKeys(for: .phoneticFullName)

// All keys needed for vCard export
CNContactVCardSerialization.descriptorForRequiredKeys()

Always prefer formatter descriptors over manual key lists for name display.

Part 3: CNMutableContact

Mutable subclass of CNContact. Not thread-safe — use immutable CNContact for cross-thread access.

Creating a Contact

let contact = CNMutableContact()
contact.givenName = "Jane"
contact.familyName = "Appleseed"
contact.organizationName = "Apple Inc."
contact.jobTitle = "Engineer"

// Phone numbers
contact.phoneNumbers = [
    CNLabeledValue(label: CNLabelPhoneNumberMobile,
                   value: CNPhoneNumber(stringValue: "+15551234567")),
    CNLabeledValue(label: CNLabelWork,
                   value: CNPhoneNumber(stringValue: "+15559876543"))
]

// Email addresses
contact.emailAddresses = [
    CNLabeledValue(label: CNLabelHome, value: "jane@example.com" as NSString),
    CNLabeledValue(label: CNLabelWork, value: "jane@apple.com" as NSString)
]

// Postal addresses
let address = CNMutablePostalAddress()
address.street = "1 Apple Park Way"
address.city = "Cupertino"
address.state = "CA"
address.postalCode = "95014"
address.country = "United States"
contact.postalAddresses = [CNLabeledValue(label: CNLabelWork, value: address)]

// Birthday
contact.birthday = DateComponents(year: 1990, month: 6, day: 15)

// Photo
contact.imageData = imageData

Removing Values

Set strings/arrays to empty, other properties to nil.

Constraint

"You may modify only those properties whose values you fetched from the contacts database."

Part 4: CNSaveRequest

Batch operations for contacts, groups, and subgroups.

Platform: iOS 9.0+, iPadOS 9.0+, macOS 10.11+, Mac Catalyst 13.1+ (no watchOS)

Contact Operations

let request = CNSaveRequest()
request.add(contact, toContainerWithIdentifier: containerId)  // nil = default
request.update(contact)
request.delete(contact)

Group Operations

request.add(group, toContainerWithIdentifier: containerId)
request.update(group)
request.delete(group)
request.addMember(contact, to: group)
request.removeMember(contact, from: group)
request.addSubgroup(subgroup, to: parentGroup)
request.removeSubgroup(subgroup, from: parentGroup)

Properties

Execution

try store.execute(request)

Concurrency: "Last change wins" for overlapping concurrent changes.

Part 5: CNContactFormatter

Locale-aware name formatting.

let formatter = CNContactFormatter()

// Format name
let name = formatter.string(from: contact)  // String?
let name = CNContactFormatter.string(from: contact, style: .fullName)

// Attributed string variants
let attributed = formatter.attributedString(from: contact)

// Locale information
let order = CNContactFormatter.nameOrder(for: contact)  // .givenNameFirst, .familyNameFirst
let delimiter = CNContactFormatter.delimiter(for: contact)  // Locale-appropriate separator

Styles

Part 6: CNContactVCardSerialization

// Export contacts to vCard data
let data = try CNContactVCardSerialization.data(with: contacts)

// Import contacts from vCard data
let contacts = try CNContactVCardSerialization.contacts(with: data)

// Required keys for export
let keys = CNContactVCardSerialization.descriptorForRequiredKeys()

Part 7: ContactsUI

CNContactPickerViewController (iOS 9+)

Lets users pick contacts without requiring app-level authorization. App receives one-time snapshot.

let picker = CNContactPickerViewController()
picker.delegate = self
picker.displayedPropertyKeys = [CNContactPhoneNumbersKey, CNContactEmailAddressesKey]
present(picker, animated: true)

Predicates (set BEFORE presentation)

// Which contacts are selectable
picker.predicateForEnablingContact = NSPredicate(
    format: "phoneNumbers.@count > 0"
)

// Auto-select whole contact (skip property selection)
picker.predicateForSelectionOfContact = NSPredicate(
    format: "emailAddresses.@count > 0"
)

// Which properties can be selected individually
picker.predicateForSelectionOfProperty = NSPredicate(
    format: "key == 'phoneNumbers'"
)

Gotcha: Changing predicates only takes effect before the view is presented.

Delegate (CNContactPickerDelegate)

func contactPicker(_ picker: CNContactPickerViewController,
                   didSelect contact: CNContact) { }
func contactPicker(_ picker: CNContactPickerViewController,
                   didSelect contacts: [CNContact]) { }  // Multi-selection
func contactPicker(_ picker: CNContactPickerViewController,
                   didSelect contactProperty: CNContactProperty) { }
func contactPickerDidCancel(_ picker: CNContactPickerViewController) { }

CNContactViewController (iOS 9+)

Display a single contact with three initialization modes:

// Existing contact
let vc = CNContactViewController(for: contact)

// Unknown contact (partial data)
let vc = CNContactViewController(forUnknownContact: partialContact)

// New contact
let vc = CNContactViewController(forNewContact: nil)

// Display mode
vc.allowsEditing = true
vc.allowsActions = true  // Call, message, email buttons
vc.displayedPropertyKeys = [CNContactPhoneNumbersKey]
vc.highlightProperty(withKey: CNContactPhoneNumbersKey, identifier: nil)

Part 8: Contact Access Button (iOS 18+)

SwiftUI component for privacy-conscious contact access.

ContactAccessButton(queryString: searchText) { identifiers in
    let contacts = await fetchContacts(withIdentifiers: identifiers)
}

Caption Options

Modifiers

.font(.system(weight: .bold))
.foregroundStyle(.gray)
.tint(.green)
.contactAccessButtonCaption(.phone)
.contactAccessButtonStyle(ContactAccessButton.Style(imageWidth: 30))

Security

Button only grants access when:

• Legible: Sufficient contrast between text and background
• Unobstructed: Entire button visible, not clipped
• Validated tap: Real user interaction, not simulated

Part 9: contactAccessPicker (iOS 18+)

Modal sheet for managing limited access contact set. For bulk or non-immediate use cases.

@State private var isPresented = false

Button("Share More Contacts") {
    isPresented.toggle()
}
.contactAccessPicker(isPresented: $isPresented) { identifiers in
    // identifiers: [String] — newly permitted contacts only
    let contacts = await fetchContacts(withIdentifiers: identifiers)
}

Difference from CNContactPickerViewController: contactAccessPicker changes persistent access. CNContactPickerViewController provides one-time snapshots.

Part 10: ContactProvider Framework (iOS 18+)

Enables apps to expose contacts to the system Contacts ecosystem from third-party sources.

Architecture

1. Main app controls the extension via ContactProviderManager
2. Extension enumerates contacts to the system
3. Communication via App Group shared container

ContactProviderManager (Main App Only)

let manager = try ContactProviderManager(domainIdentifier: "com.myapp.contacts")

try await manager.enable()            // Async — may prompt user
try await manager.disable()           // Deactivate
try await manager.reset()             // Clear all provider contacts
try await manager.invalidate()        // Terminate extension
try await manager.signalEnumerator(for: .default)  // Trigger enumeration

manager.isEnabled                     // Bool — activation state

Cannot be used in app extensions — main app only.

ContactProviderExtension Protocol

@main
class Provider: ContactProviderExtension {
    func configure(for domain: ContactProviderDomain) {
        // Setup data access
    }

    func enumerator(for collection: ContactItem.Identifier)
        -> ContactItemEnumerator {
        return MyEnumerator()
    }

    func invalidate() async throws {
        // Cleanup
    }
}

Info.plist: Extension point com.apple.contact.provider.extension

Enumeration

Two patterns:

1. Content enumeration — full initial sync via ContactItemContentObserver
2. Change enumeration — incremental updates via ContactItemChangeObserver and ContactItemSyncAnchor

class MyEnumerator: ContactItemEnumerator {
    func enumerateContent(
        in page: ContactItemPage,
        for observer: ContactItemContentObserver
    ) {
        let contact = CNMutableContact()
        contact.givenName = "Jane"
        contact.familyName = "Appleseed"
        let item = ContactItem.contact(contact, ContactItem.Identifier("jane-001"))
        observer.didEnumerate([item])
        observer.didFinishEnumeratingContent(upTo: generationMarker)
    }

    func enumerateChanges(
        startingAt anchor: ContactItemSyncAnchor,
        for observer: ContactItemChangeObserver
    ) {
        // Incremental updates since anchor
        observer.didFinishEnumeratingChanges(upTo: newAnchor)
    }
}

ContactProvider Errors

Part 11: Change History (TN3149)

CNChangeHistoryFetchRequest

let request = CNChangeHistoryFetchRequest()
request.startingToken = savedToken           // nil = full fetch
request.includeGroupChanges = false          // Default NO
request.mutableObjects = false               // Default NO
request.shouldUnifyResults = true            // Default YES
request.additionalContactKeyDescriptors = [
    CNContactFormatter.descriptorForRequiredKeys(for: .fullName)
]
request.excludedTransactionAuthors = [Bundle.main.bundleIdentifier!]

CNChangeHistoryEventVisitor Protocol

// Required
func visit(_ event: CNChangeHistoryDropEverythingEvent)   // Full re-sync
func visit(_ event: CNChangeHistoryAddContactEvent)        // New contact
func visit(_ event: CNChangeHistoryUpdateContactEvent)     // Modified
func visit(_ event: CNChangeHistoryDeleteContactEvent)     // Deleted

// Optional (when includeGroupChanges = true)
func visit(_ event: CNChangeHistoryAddGroupEvent)
func visit(_ event: CNChangeHistoryUpdateGroupEvent)
func visit(_ event: CNChangeHistoryDeleteGroupEvent)
func visit(_ event: CNChangeHistoryAddMemberToGroupEvent)
func visit(_ event: CNChangeHistoryRemoveMemberFromGroupEvent)
func visit(_ event: CNChangeHistoryAddSubgroupToGroupEvent)
func visit(_ event: CNChangeHistoryRemoveSubgroupFromGroupEvent)

Must use visitor pattern — do NOT use isKindOfClass: to determine event type.

Gotcha: enumeratorForChangeHistoryFetchRequest:error: is Objective-C only — unavailable in Swift.

Token expiration: Returns DropEverything + Add events for all contacts — same code handles full and incremental sync.

Transaction authors: Use reverse-domain notation (bundle identifier). Filters results but doesn't provide attribution.

Part 12: Error Reference

CNError Codes

Error userInfo provides: affectedRecords, affectedRecordIdentifiers, keyPaths.

Part 13: Platform Availability

Resources

WWDC: 2024-10121

Docs: /contacts, /contacts/cncontactstore, /contacts/cnmutablecontact, /contactsui, /contactsui/cncontactpickerviewcontroller, /contactprovider, /technotes/tn3149

Skills: contacts, eventkit-ref, privacy-ux