เครื่องมือเลือกรายชื่อติดต่อ

เครื่องมือเลือกรายชื่อติดต่อของ Android เป็นอินเทอร์เฟซที่ได้มาตรฐานและเรียกดูได้สำหรับผู้ใช้ในการ แชร์รายชื่อติดต่อกับแอปของคุณ เครื่องมือเลือกนี้พร้อมใช้งานในอุปกรณ์ที่ใช้ Android 17 ขึ้นไป และเป็นทางเลือกที่ช่วยรักษาความเป็นส่วนตัวแทนREAD_CONTACTSสิทธิ์แบบกว้าง แทนที่จะขอสิทธิ์เข้าถึงสมุดที่อยู่ทั้งหมดของผู้ใช้ แอปจะระบุฟิลด์ข้อมูลที่ต้องการ เช่น หมายเลขโทรศัพท์หรืออีเมล และผู้ใช้จะเลือกรายชื่อติดต่อที่ต้องการแชร์ได้ ซึ่งจะให้สิทธิ์การเข้าถึงแบบอ่านแก่แอปของคุณเฉพาะข้อมูลที่เลือก เพื่อให้ควบคุมได้อย่างละเอียดพร้อมมอบประสบการณ์การใช้งานที่สอดคล้องกันด้วย ความสามารถในการค้นหาในตัว การสลับโปรไฟล์ และการเลือกหลายรายการโดยไม่ต้อง สร้างหรือดูแลรักษา UI

ผสานรวมเครื่องมือเลือกรายชื่อติดต่อ

หากต้องการผสานรวมเครื่องมือเลือกรายชื่อติดต่อ ให้ใช้ Intent.ACTION_PICK_CONTACTS Intent Intent นี้จะเปิดตัวเครื่องมือเลือกและส่งคืนรายชื่อติดต่อที่เลือกไปยังแอปของคุณ

เครื่องมือเลือกรายชื่อติดต่อช่วยให้คุณระบุฟิลด์ข้อมูลหลายรายการที่แอปต้องการได้พร้อมกัน ซึ่งแตกต่างจาก ACTION_PICK แบบเดิม โดยทำได้โดยใช้ Intent.EXTRA_REQUESTED_DATA_FIELDS ส่ง ArrayList<String> ของ MIME types ที่กำหนดไว้ใน ContactsContract.CommonDataKinds

ประเภท MIME ทั่วไป ได้แก่

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

เปิดเครื่องมือเลือก

ใช้ registerForActivityResult กับสัญญา StartActivityForResult เพื่อ เปิดตัวเครื่องมือเลือก คุณกำหนดค่า Intent เพื่ออนุญาตการเลือกรายการเดียวหรือหลายรายการได้

เลือกรายชื่อติดต่อเดียว

ในตัวอย่างนี้ แอปขอเฉพาะหมายเลขโทรศัพท์ เครื่องมือเลือกจะกรอง รายชื่อเพื่อแสดงเฉพาะรายชื่อติดต่อที่มีหมายเลขโทรศัพท์และอนุญาตให้ผู้ใช้เลือกหมายเลข ที่ต้องการ

Kotlin

// Define the specific data fields you need
val requestedFields = arrayListOf(
    ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE
)

// Set up the intent
val pickContactIntent = Intent(Intent.ACTION_PICK_CONTACTS).apply {
    type = ContactsContract.Contacts.CONTENT_TYPE
    putStringArrayListExtra(Intent.EXTRA_REQUESTED_DATA_FIELDS, requestedFields)
}

// Launch the picker
pickContactLauncher.launch(pickContactIntent)

Java

// Define the specific data fields you need
ArrayList<String> requestedFields = new ArrayList<>();
requestedFields.add(ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE);

// Set up the intent
Intent pickContactIntent = new Intent(Intent.ACTION_PICK_CONTACTS);
pickContactIntent.setType(ContactsContract.Contacts.CONTENT_TYPE);
pickContactIntent.putStringArrayListExtra(Intent.EXTRA_REQUESTED_DATA_FIELDS,
        requestedFields);

// Launch the picker
pickContactLauncher.launch(pickContactIntent);

เลือกรายชื่อติดต่อหลายรายการ

หากต้องการเปิดใช้การเลือกหลายรายการ ให้เพิ่ม Intent.EXTRA_ALLOW_MULTIPLE extra คุณ จำกัดจำนวนรายการที่ผู้ใช้เลือกได้ (ไม่บังคับ)

Kotlin

val requestedFields = arrayListOf(
    ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE,
    ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE
)

val pickMultipleIntent = Intent(Intent.ACTION_PICK_CONTACTS).apply {
    type = ContactsContract.Contacts.CONTENT_TYPE
    putStringArrayListExtra(Intent.EXTRA_REQUESTED_DATA_FIELDS, requestedFields)
    // Enable multi-select
    putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true)
    // Optional: Set a custom limit (max 50 recommended)
    putExtra(Intent.EXTRA_SELECTION_LIMIT, 10)
}

pickMultipleLauncher.launch(pickMultipleIntent)

จัดการผลลัพธ์

เมื่อผู้ใช้เลือกเสร็จสมบูรณ์แล้ว ระบบจะแสดง RESULT_OK และ URI ของเซสชัน URI นี้ให้สิทธิ์การอ่านชั่วคราวสำหรับข้อมูลที่เลือก

คุณสามารถค้นหา URI นี้ได้โดยใช้ ContentResolver มาตรฐาน Cursor ที่ได้จะมีช่องข้อมูลที่ขอและเป็นไปตามสคีมาของ ContactsContract.Data

Kotlin

private val pickContactLauncher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
        // The result data contains the Session URI
        val sessionUri = result.data?.data
        sessionUri?.let { uri ->
            processSelectedContacts(uri)
        }
    } else {
        // User cancelled the picker
    }
}

private fun processSelectedContacts(sessionUri: Uri) {
    // Define the projection (columns) you want to retrieve
    val projection = arrayOf(
        ContactsContract.Data.CONTACT_ID,
        ContactsContract.Contacts.DISPLAY_NAME_PRIMARY,
        ContactsContract.Data.MIMETYPE,
        ContactsContract.Data.DATA1 // Generic data column (Phone number, Email, etc.)
    )

    contentResolver.query(sessionUri, projection, null, null, null)?.use { cursor ->
        val mimeTypeIdx = cursor.getColumnIndex(ContactsContract.Data.MIMETYPE)
        val dataIdx = cursor.getColumnIndex(ContactsContract.Data.DATA1)
        val nameIdx = cursor.getColumnIndex(ContactsContract.Contacts.DISPLAY_NAME_PRIMARY)

        while (cursor.moveToNext()) {
            val mimeType = cursor.getString(mimeTypeIdx)
            val dataValue = cursor.getString(dataIdx)
            val name = cursor.getString(nameIdx)

            when (mimeType) {
                ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE -> {
                    Log.d("ContactPicker", "Picked Phone: $dataValue for $name")
                }
                ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE -> {
                    Log.d("ContactPicker", "Picked Email: $dataValue for $name")
                }
            }
        }
    }
}

ความเข้ากันได้แบบย้อนหลัง

สำหรับแอปที่กำหนดเป้าหมายเป็น Android 17 ขึ้นไป ระบบจะ อัปเกรด Intent.ACTION_PICK Intent ที่มีอยู่โดยอัตโนมัติเพื่อใช้ อินเทอร์เฟซเครื่องมือเลือกรายชื่อติดต่อใหม่

หากแอปใช้ ACTION_PICK อยู่แล้ว คุณไม่จำเป็นต้องเปลี่ยนโค้ดเพื่อ รับ UI ใหม่ อย่างไรก็ตาม หากต้องการใช้ประโยชน์จากฟีเจอร์ใหม่ๆ เช่น รับ Uri รายการเดียวเพื่อค้นหาข้อมูลรายชื่อติดต่อ การสลับระหว่างโปรไฟล์ส่วนตัวและโปรไฟล์งาน หรือคำขอฟิลด์ข้อมูลหลายรายการ คุณต้องอัปเดตการติดตั้งใช้งานเพื่อใช้ Intent.ACTION_PICK_CONTACTS หรือส่วนเสริม Intent ใหม่

การทดสอบใน SDK รุ่นเก่า

คุณสามารถทดสอบลักษณะการทำงานใหม่ของเครื่องมือเลือกในอุปกรณ์ที่ใช้ Android 17 ขึ้นไปได้ แม้ว่าแอปจะกำหนดเป้าหมายเป็น SDK เวอร์ชันที่ต่ำกว่าก็ตาม โดยการเพิ่มEXTRA_USE_SYSTEM_CONTACTS_PICKERบูลีนพิเศษลงใน Intent ของ ACTION_PICK

แนวทางปฏิบัติแนะนำ

• ขอเฉพาะสิ่งที่จำเป็น: หากแอปของคุณต้องการส่ง SMS เท่านั้น ให้ขอ Phone.CONTENT_ITEM_TYPE เครื่องมือเลือกจะกรองรายชื่อติดต่อที่ไม่มีหมายเลขโทรศัพท์ออกโดยอัตโนมัติ ทำให้ UI สำหรับผู้ใช้ดูสะอาดตามากขึ้น
• คงข้อมูลทันที: URI ของเซสชันให้สิทธิ์อ่านชั่วคราว หากต้องการเข้าถึงข้อมูลติดต่อนี้ในภายหลัง (หลังจากระบบปิดกระบวนการของแอป) แอปจะต้องเก็บข้อมูลติดต่อไว้
• อย่าใช้ข้อมูลบัญชี: ระบบจะนำข้อมูลเมตาเฉพาะบัญชีออกจากผลการค้นหาเพื่อปกป้องความเป็นส่วนตัวของผู้ใช้และป้องกันการลายนิ้วมือ