Công cụ chọn người liên hệ

Bộ chọn người liên hệ của Android là một giao diện chuẩn hoá, có thể duyệt xem để người dùng chia sẻ người liên hệ với ứng dụng của bạn. Có trên các thiết bị chạy Android 17 (API cấp 37) trở lên, bộ chọn này là một giải pháp thay thế đảm bảo quyền riêng tư cho quyền READ_CONTACTS rộng. Thay vì yêu cầu quyền truy cập vào toàn bộ sổ địa chỉ của người dùng, ứng dụng của bạn sẽ chỉ định các trường dữ liệu cần thiết (chẳng hạn như số điện thoại hoặc địa chỉ email) và người dùng sẽ chọn những người liên hệ cụ thể để chia sẻ. Điều này cấp cho ứng dụng của bạn quyền đọc chỉ đối với dữ liệu đã chọn, đảm bảo quyền kiểm soát chi tiết, đồng thời mang lại trải nghiệm nhất quán cho người dùng nhờ các tính năng tìm kiếm, chuyển đổi hồ sơ trên Tìm kiếm và chọn nhiều mục tích hợp sẵn mà không cần phải xây dựng hoặc duy trì giao diện người dùng.

Tích hợp Trình chọn người liên hệ

Để tích hợp Trình chọn người liên hệ, hãy dùng ý định ContactsPickerSessionContract.ACTION_PICK_CONTACTS. Ý định này sẽ khởi chạy trình chọn người liên hệ và trả về các địa chỉ liên hệ đã chọn cho ứng dụng của bạn.

Không giống như ACTION_PICK cũ, Trình chọn người liên hệ cho phép bạn chọn cùng lúc nhiều trường dữ liệu mà ứng dụng của bạn yêu cầu. Bạn thực hiện việc này bằng cách sử dụng ContactsPickerSessionContract.EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS, truyền một ArrayList<String> của các loại MIME được xác định trong ContactsContract.CommonDataKinds.

Các loại MIME phổ biến bao gồm:

  • ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE
  • ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE
  • ContactsContract.CommonDataKinds.StructuredPostal.CONTENT_ITEM_TYPE

Chạy bộ chọn

Sử dụng registerForActivityResult với hợp đồng StartActivityForResult để khởi chạy công cụ chọn. Bạn có thể định cấu hình ý định để cho phép chọn một hoặc nhiều mục.

// Launcher for the Contact Picker intent
val pickContact = rememberLauncherForActivityResult(StartActivityForResult()) {
    if (it.resultCode == Activity.RESULT_OK) {
        val resultUri = it.data?.data ?: return@rememberLauncherForActivityResult

        // Process the result URI in a background thread to fetch all selected contacts
        coroutine.launch {
            contacts = processContactPickerResultUri(resultUri, context)
        }
    }
}

Chế độ chọn

Giao diện người dùng của Trình chọn người liên hệ sẽ điều chỉnh theo các trường dữ liệu được yêu cầu. Tuỳ thuộc vào các yêu cầu này, người dùng có thể chọn toàn bộ bản ghi liên hệ khi cần nhiều trường hoặc chọn các mục dữ liệu cụ thể trong thông tin của người liên hệ.

Các chế độ giao diện người dùng khác nhau của Trình chọn người liên hệ
Hình 1. Giao diện Trình chọn người liên hệ sẽ điều chỉnh theo các trường dữ liệu được yêu cầu (chọn một người liên hệ, nhiều người liên hệ và nhiều số điện thoại).

Chọn một người liên hệ

Trong ví dụ này, ứng dụng chỉ yêu cầu số điện thoại. Bộ chọn sẽ lọc danh sách để chỉ hiển thị những người liên hệ có số điện thoại và cho phép người dùng chọn một số điện thoại cụ thể.

// Define the specific contact data fields you need
val requestedFields = arrayListOf(
    Email.CONTENT_ITEM_TYPE,
    Phone.CONTENT_ITEM_TYPE,
)

// Set up the intent for the Contact Picker
val pickContactIntent = Intent(ACTION_PICK_CONTACTS).apply {
    putExtra(EXTRA_USE_SYSTEM_CONTACTS_PICKER, true)
    putStringArrayListExtra(
        EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS,
        requestedFields
    )
}

// Launch the picker
pickContact.launch(pickContactIntent)

Chọn nhiều người liên hệ

Để bật tính năng chọn nhiều mục, hãy thêm Intent.EXTRA_ALLOW_MULTIPLE bổ sung. Bạn có thể giới hạn số lượng mục mà người dùng có thể chọn.

val requestedFields = arrayListOf(
    Email.CONTENT_ITEM_TYPE,
    Phone.CONTENT_ITEM_TYPE,
)

// Set up the intent for the Contact Picker
val pickContactIntent = Intent(ACTION_PICK_CONTACTS).apply {
    putExtra(EXTRA_USE_SYSTEM_CONTACTS_PICKER, true)
    // Enable multi-select
    putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true)
    // Set limit of selectable contacts
    putExtra(EXTRA_PICK_CONTACTS_SELECTION_LIMIT, 5)
    // Define the specific contact data fields you need
    putStringArrayListExtra(
        EXTRA_PICK_CONTACTS_REQUESTED_DATA_FIELDS,
        requestedFields
    )
    // Enable this option to only filter contacts that have all the requested data fields
    putExtra(EXTRA_PICK_CONTACTS_MATCH_ALL_DATA_FIELDS, false)
}

// Launch the picker
pickContact.launch(pickContactIntent)

Xử lý kết quả

Khi người dùng hoàn tất lựa chọn, hệ thống sẽ trả về một RESULT_OK và một URI phiên. URI này cấp quyền đọc tạm thời cho dữ liệu đã chọn.

Bạn có thể truy vấn URI này bằng ContentResolver chuẩn. Cursor thu được chứa các trường dữ liệu được yêu cầu và tuân theo giản đồ của ContactsContract.Data.

// Data class representing a parsed Contact with selected details.
data class Contact(
    val lookupKey: String,
    val name: String,
    val emails: List<String>,
    val phones: List<String>
)

// Helper function to query the content resolver with the URI returned by the Contact Picker.
// Parses the cursor to extract contact details such as name, email, and phone number.
private suspend fun processContactPickerResultUri(
    sessionUri: Uri,
    context: Context
): List<Contact> = withContext(Dispatchers.IO) {
    // Define the columns we want to retrieve from the ContactPicker ContentProvider
    val projection = arrayOf(
        ContactsContract.Contacts.LOOKUP_KEY,
        ContactsContract.Contacts.DISPLAY_NAME_PRIMARY,
        ContactsContract.Data.MIMETYPE, // Type of data (e.g., email or phone)
        ContactsContract.Data.DATA1, // The actual data (Phone number / Email string)
    )

    // We use `LOOKUP_KEY` as a unique ID to aggregate all contact info related to a same person
    val contactsMap = mutableMapOf<String, Contact>()

    // Note: The Contact Picker Session Uri doesn't support custom selection & selectionArgs.
    // We query the URI directly to get the results chosen by the user.
    context.contentResolver.query(sessionUri, projection, null, null, null)?.use { cursor ->
        // Get the column indices for our requested projection
        val lookupKeyIdx = cursor.getColumnIndex(ContactsContract.Contacts.LOOKUP_KEY)
        val mimeTypeIdx = cursor.getColumnIndex(ContactsContract.Data.MIMETYPE)
        val nameIdx = cursor.getColumnIndex(ContactsContract.Contacts.DISPLAY_NAME_PRIMARY)
        val data1Idx = cursor.getColumnIndex(ContactsContract.Data.DATA1)

        while (cursor.moveToNext()) {
            val lookupKey = cursor.getString(lookupKeyIdx)
            val mimeType = cursor.getString(mimeTypeIdx)
            val name = cursor.getString(nameIdx) ?: ""
            val data1 = cursor.getString(data1Idx) ?: ""

            val email = if (mimeType == Email.CONTENT_ITEM_TYPE) data1 else null
            val phone = if (mimeType == Phone.CONTENT_ITEM_TYPE) data1 else null

            val existingContact = contactsMap[lookupKey]
            if (existingContact != null) {
                contactsMap[lookupKey] = existingContact.copy(
                    emails = if (email != null) existingContact.emails + email else existingContact.emails,
                    phones = if (phone != null) existingContact.phones + phone else existingContact.phones
                )
            } else {
                contactsMap[lookupKey] = Contact(
                    lookupKey = lookupKey,
                    name = name,
                    emails = if (email != null) listOf(email) else emptyList(),
                    phones = if (phone != null) listOf(phone) else emptyList()
                )
            }
        }
    }

    return@withContext contactsMap.values.toList()
}

Khả năng tương thích ngược

Đối với các ứng dụng nhắm đến Android 17 (API cấp 37) trở lên, hệ thống sẽ tự động nâng cấp ý định Intent.ACTION_PICK hiện có để sử dụng giao diện Trình chọn người liên hệ mới.

Nếu ứng dụng của bạn đã sử dụng ACTION_PICK, thì bạn không cần thay đổi mã để nhận giao diện người dùng mới. Tuy nhiên, để tận dụng các tính năng mới, chẳng hạn như nhận một Uri duy nhất để truy vấn dữ liệu liên hệ, chuyển đổi giữa hồ sơ cá nhân và hồ sơ công việc hoặc nhiều yêu cầu về trường dữ liệu, bạn phải cập nhật quy trình triển khai để sử dụng ContactsPickerSessionContract.ACTION_PICK_CONTACTS hoặc các ý định bổ sung mới.

Thử nghiệm trên các SDK mục tiêu cũ hơn

Bạn có thể kiểm thử hành vi mới của bộ chọn trên các thiết bị chạy Android 17 trở lên, ngay cả khi ứng dụng của bạn nhắm đến phiên bản SDK thấp hơn, bằng cách thêm boolean bổ sung EXTRA_USE_SYSTEM_CONTACTS_PICKER vào ý định ACTION_PICK.

Các phương pháp hay nhất

  • Chỉ yêu cầu những quyền bạn cần: Nếu ứng dụng của bạn chỉ cần gửi tin nhắn SMS, hãy yêu cầu quyền Phone.CONTENT_ITEM_TYPE. Bộ chọn sẽ tự động lọc ra những người liên hệ không có số điện thoại, giúp giao diện người dùng trở nên gọn gàng hơn.
  • Quản lý nhiều mục dữ liệu cho mỗi người liên hệ: Mỗi người liên hệ thường có nhiều địa chỉ email hoặc số điện thoại. Để đảm bảo các lựa chọn này được trình bày rõ ràng và trực quan cho người dùng, bạn nên nhóm các lựa chọn đó bằng ContactsContract.Contacts.LOOKUP_KEY. Hơn nữa, bạn có thể truy xuất các nhãn cụ thể cho từng mục (chẳng hạn như công việc hoặc cá nhân) để cung cấp các lựa chọn chi tiết hơn trong giao diện của ứng dụng.
  • Lưu trữ dữ liệu ngay lập tức: URI phiên cấp quyền đọc tạm thời. Nếu cần truy cập vào thông tin liên hệ này sau (sau khi quy trình ứng dụng của bạn bị tắt), thì ứng dụng của bạn phải lưu giữ dữ liệu liên hệ.
  • Không dựa vào Dữ liệu tài khoản: Để bảo vệ quyền riêng tư của người dùng và ngăn chặn việc lấy vân tay số, siêu dữ liệu dành riêng cho tài khoản sẽ bị xoá khỏi kết quả.