با انتخابگر تماس بگیرید

انتخابگر مخاطب اندروید (Android Contact Picker) یک رابط کاربری استاندارد و قابل مرور برای کاربران است تا مخاطبین را با برنامه شما به اشتراک بگذارند. این انتخابگر که در دستگاه‌های دارای اندروید ۱۷ یا بالاتر موجود است، جایگزینی برای مجوز گسترده READ_CONTACTS با حفظ حریم خصوصی ارائه می‌دهد. برنامه شما به جای درخواست دسترسی به کل دفترچه آدرس کاربر، فیلدهای داده مورد نیاز خود، مانند شماره تلفن یا آدرس ایمیل را مشخص می‌کند و کاربر مخاطبین خاصی را برای اشتراک‌گذاری انتخاب می‌کند. این امر به برنامه شما اجازه می‌دهد تا فقط به داده‌های انتخاب شده دسترسی داشته باشد و کنترل دقیق را تضمین کند و در عین حال یک تجربه کاربری سازگار با قابلیت‌های جستجوی داخلی، تغییر پروفایل و انتخاب چندگانه را بدون نیاز به ساخت یا نگهداری رابط کاربری ارائه دهد.

انتخابگر مخاطب را ادغام کنید

برای ادغام انتخابگر مخاطب، از Intent.ACTION_PICK_CONTACTS استفاده کنید. این intent انتخابگر را اجرا می‌کند و مخاطبین انتخاب شده را به برنامه شما برمی‌گرداند.

برخلاف ACTION_PICK قدیمی، Contact Picker به شما امکان می‌دهد چندین فیلد داده‌ای را که برنامه شما به طور همزمان نیاز دارد، مشخص کنید. شما این کار را با استفاده از Intent.EXTRA_REQUESTED_DATA_FIELDS انجام می‌دهید و یک ArrayList<String> از انواع MIME تعریف شده در ContactsContract.CommonDataKinds را ارسال می‌کنید.

انواع MIME رایج عبارتند از:

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

انتخابگر را راه اندازی کنید

registerForActivityResult به همراه قرارداد StartActivityForResult برای اجرای انتخابگر (picker) استفاده کنید. می‌توانید اینتنت را طوری پیکربندی کنید که امکان انتخاب تکی یا چندگانه را فراهم کند.

یک مخاطب واحد را انتخاب کنید

در این مثال، برنامه فقط شماره تلفن‌ها را درخواست می‌کند. انتخابگر، لیست را فیلتر می‌کند تا فقط مخاطبین دارای شماره تلفن را نشان دهد و به کاربر اجازه دهد یک شماره خاص را انتخاب کند.

کاتلین

// 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)

جاوا

// 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 را اضافه کنید. می‌توانید به صورت اختیاری تعداد مواردی را که کاربر می‌تواند انتخاب کند محدود کنید.

کاتلین

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 و یک Session URI برمی‌گرداند. این URI دسترسی موقت خواندن به داده‌های انتخاب شده را اعطا می‌کند.

شما می‌توانید با استفاده از یک ContentResolver استاندارد، این URI را جستجو کنید. Cursor حاصل شامل فیلدهای داده درخواستی است و از طرح ContactsContract.Data پیروی می‌کند.

کاتلین

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")
                }
            }
        }
    }
}

سازگاری با نسخه‌های قبلی

برای برنامه‌هایی که اندروید ۱۷ و بالاتر را هدف قرار می‌دهند، سیستم به طور خودکار Intent.ACTION_PICK موجود را برای استفاده از رابط کاربری جدید Contact Picker ارتقا می‌دهد.

اگر برنامه شما از قبل از ACTION_PICK استفاده می‌کند، نیازی به تغییر کد خود برای دریافت رابط کاربری جدید ندارید. با این حال، برای بهره‌مندی از ویژگی‌های جدید، مانند دریافت یک Uri واحد برای جستجوی داده‌های مخاطب، جابجایی بین پروفایل‌های شخصی و کاری یا درخواست‌های فیلد داده چندگانه، باید پیاده‌سازی خود را برای استفاده از Intent.ACTION_PICK_CONTACTS یا موارد اضافی جدید intent به‌روزرسانی کنید.

آزمایش روی SDK های قدیمی تر

شما می‌توانید رفتار جدید انتخابگر را روی دستگاه‌هایی که اندروید ۱۷ و بالاتر دارند، حتی اگر برنامه شما نسخه SDK پایین‌تری را هدف قرار داده است، با اضافه کردن مقدار بولی EXTRA_USE_SYSTEM_CONTACTS_PICKER به تابع ACTION_PICK خود، آزمایش کنید.

بهترین شیوه‌ها

• فقط مواردی را که نیاز دارید درخواست کنید : اگر برنامه شما فقط نیاز به ارسال پیامک دارد، Phone.CONTENT_ITEM_TYPE را درخواست کنید. انتخابگر به طور خودکار مخاطبینی را که شماره تلفن ندارند فیلتر می‌کند و در نتیجه رابط کاربری تمیزتری برای کاربر ایجاد می‌شود.
• داده‌ها را فوراً ذخیره کنید : آدرس اینترنتی Session، مجوز خواندن موقت را اعطا می‌کند. اگر بعداً (پس از خاتمه فرآیند برنامه) نیاز به دسترسی به این اطلاعات مخاطب داشته باشید، برنامه شما باید داده‌های مخاطب را ذخیره کند.
• به داده‌های حساب کاربری اعتماد نکنید : برای محافظت از حریم خصوصی کاربر و جلوگیری از ردیابی اثر انگشت، فراداده‌های مربوط به حساب کاربری از نتایج حذف می‌شوند.