SwiftUI中如何获取联系人关系组内的联系人头像

问题描述 #

已成功获取所有联系人及CNContactRelationsKey数据，希望实现苹果通讯录APP不具备的联系人关系组头像显示功能。当前SwiftUI代码使用SF符号作为关系联系人的占位头像，需要通过CNContactThumbnailImageDataKey获取关系联系人的头像数据并在界面中显示。

当前代码片段：

struct ContactInfoTableView: View {
    let contact: CNContact

    var relationships: [CNLabeledValue<CNContactRelation>] {
        contact.contactRelations
    }

    var body: some View {
        VStack(alignment: .leading) {
            List {
                if !relationships.isEmpty {
                    Section(header: Text("Relationships")) {
                        ForEach(relationships, id: \.self) { relation in
                            HStack {
                                if let label = relation.label {
                                    let localizedLabel = CNLabeledValue<NSString>.localizedString(forLabel: label)
                                    Text(localizedLabel)
                                }

                                Image(systemName: "person.crop.circle")
                                    .resizable()
                                    .frame(width: 24, height: 24)
                                    .padding(.leading)
                                    .foregroundColor(.gray)

                                Text(relation.value.name)
                            }
                        }
                    }
                }
            }
        }
    }
}

解决方案 #

步骤1：实现联系人头像查询工具 #

因为CNContactRelation仅包含联系人名称，需要通过名称去通讯录中匹配对应的联系人并获取头像数据。创建CNContactStore扩展来处理查询逻辑：

import Contacts

extension CNContactStore {
    func fetchContactThumbnail(for name: String) async -> UIImage? {
        let requiredKeys: [CNKeyDescriptor] = [
            CNContactThumbnailImageDataKey as CNKeyDescriptor,
            CNContactGivenNameKey as CNKeyDescriptor,
            CNContactFamilyNameKey as CNKeyDescriptor
        ]
        
        let searchPredicate = CNContact.predicateForContacts(matchingName: name)
        
        do {
            let matchedContacts = try await unifiedContacts(matching: searchPredicate, keysToFetch: requiredKeys)
            // 取第一个匹配的联系人（可根据业务需求优化匹配规则）
            guard let targetContact = matchedContacts.first,
                  let imageData = targetContact.thumbnailImageData else {
                return nil
            }
            return UIImage(data: imageData)
        } catch {
            print("查询头像失败: \(error.localizedDescription)")
            return nil
        }
    }
}

步骤2：修改SwiftUI视图异步加载头像 #

在原视图中添加状态存储头像，结合task修饰符异步获取并更新界面：

struct ContactInfoTableView: View {
    let contact: CNContact
    private let contactStore = CNContactStore()
    
    var relationships: [CNLabeledValue<CNContactRelation>] {
        contact.contactRelations
    }

    // 用联系人名称作为key，缓存已加载的头像
    @State private var relationAvatars: [String: UIImage] = [:]

    var body: some View {
        VStack(alignment: .leading) {
            List {
                if !relationships.isEmpty {
                    Section(header: Text("Relationships")) {
                        ForEach(relationships, id: \.self) { relation in
                            HStack {
                                if let label = relation.label {
                                    let localizedLabel = CNLabeledValue<NSString>.localizedString(forLabel: label)
                                    Text(localizedLabel)
                                }

                                // 显示头像或占位图
                                Group {
                                    if let avatar = relationAvatars[relation.value.name] {
                                        Image(uiImage: avatar)
                                            .resizable()
                                            .scaledToFill()
                                            .frame(width: 24, height: 24)
                                            .clipShape(Circle())
                                    } else {
                                        Image(systemName: "person.crop.circle")
                                            .resizable()
                                            .frame(width: 24, height: 24)
                                            .foregroundColor(.gray)
                                    }
                                }
                                .padding(.leading)

                                Text(relation.value.name)
                            }
                            .task {
                                // 仅当未加载过时才发起查询
                                guard relationAvatars[relation.value.name] == nil else { return }
                                if let avatar = await contactStore.fetchContactThumbnail(for: relation.value.name) {
                                    relationAvatars[relation.value.name] = avatar
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

步骤3：配置通讯录访问权限 #

在Info.plist中添加权限描述，否则无法访问通讯录：

<key>NSContactsUsageDescription</key>
<string>需要访问通讯录以显示联系人关系的头像</string>

注意事项 #

• 同名联系人处理：当前代码取第一个匹配的联系人，可根据需求优化匹配逻辑（比如结合更多字段筛选）。
• 错误与状态优化：可添加加载中的占位动画，处理权限拒绝等异常场景。
• 性能优化：可实现全局缓存，避免重复查询相同名称的联系人头像。

内容的提问来源于stack exchange，提问作者Antonio A. Chavez