مخاطبین را با استفاده از intent تغییر دهید

این درس به شما نشان می دهد که چگونه از یک Intent برای درج یک مخاطب جدید یا تغییر داده های یک مخاطب استفاده کنید. یک Intent به جای دسترسی مستقیم به Contacts Provider، برنامه مخاطبین را راه اندازی می کند که Activity مناسب را اجرا می کند. برای اقدامات اصلاحی توضیح داده شده در این درس، اگر داده های توسعه یافته را در Intent ارسال کنید، در UI Activity که شروع شده است وارد می شود.

استفاده از Intent برای درج یا به‌روزرسانی یک مخاطب، روش ترجیحی برای تغییر ارائه‌دهنده مخاطبین است، به دلایل زیر:

  • در زمان و تلاش شما برای توسعه UI و کد خود صرفه جویی می کند.
  • از ارائه خطاهای ناشی از تغییراتی که از قوانین ارائه‌دهنده مخاطبین پیروی نمی‌کنند، جلوگیری می‌کند.
  • تعداد مجوزهای مورد نیاز برای درخواست را کاهش می دهد. برنامه شما برای نوشتن به ارائه‌دهنده مخاطبین نیازی به مجوز ندارد، زیرا تغییرات را به برنامه مخاطبین که قبلاً این مجوز را دارد واگذار می‌کند.

با استفاده از intent یک مخاطب جدید وارد کنید

وقتی برنامه شما داده های جدیدی دریافت می کند، اغلب می خواهید به کاربر اجازه دهید مخاطب جدیدی را وارد کند. به عنوان مثال، یک برنامه بررسی رستوران می تواند به کاربران اجازه دهد تا رستوران را به عنوان مخاطب در حین بررسی آن اضافه کنند. برای انجام این کار با استفاده از یک intent، با استفاده از داده‌هایی که در دسترس دارید، intent را ایجاد کنید و سپس آن را به برنامه مخاطبین ارسال کنید.

درج یک مخاطب با استفاده از برنامه مخاطبین، یک مخاطب خام جدید را در جدول ContactsContract.RawContacts ارائه دهنده مخاطبین قرار می دهد. در صورت لزوم، برنامه مخاطبین از کاربران می‌خواهد که از نوع حساب و حسابی که در هنگام ایجاد مخاطب خام استفاده کنند، استفاده کنند. اگر مخاطب خام از قبل وجود داشته باشد، اپلیکیشن مخاطبین نیز به کاربران اطلاع می دهد. سپس کاربران گزینه لغو درج را دارند، در این صورت هیچ تماسی ایجاد نمی شود. برای کسب اطلاعات بیشتر در مورد مخاطبین خام، راهنمای API ارائه دهنده مخاطبین را ببینید.

یک قصد ایجاد کنید

برای شروع، یک شی Intent جدید با عمل Intents.Insert.ACTION ایجاد کنید. نوع MIME را روی RawContacts.CONTENT_TYPE تنظیم کنید. به عنوان مثال:

کاتلین

...
// Creates a new Intent to insert a contact
val intent = Intent(ContactsContract.Intents.Insert.ACTION).apply {
    // Sets the MIME type to match the Contacts Provider
    type = ContactsContract.RawContacts.CONTENT_TYPE
}

جاوا

...
// Creates a new Intent to insert a contact
Intent intent = new Intent(ContactsContract.Intents.Insert.ACTION);
// Sets the MIME type to match the Contacts Provider
intent.setType(ContactsContract.RawContacts.CONTENT_TYPE);

اگر از قبل جزئیاتی برای مخاطب دارید، مانند شماره تلفن یا آدرس ایمیل، می توانید آنها را به عنوان داده توسعه یافته در intent وارد کنید. برای یک مقدار کلید، از ثابت مناسب از Intents.Insert استفاده کنید. برنامه مخاطبین داده‌ها را در صفحه نمایش درج خود نمایش می‌دهد و به کاربران امکان می‌دهد ویرایش‌ها و اضافات بیشتری را انجام دهند.

کاتلین

private var emailAddress: EditText? = null
private var phoneNumber: EditText? = null
...
/* Assumes EditText fields in your UI contain an email address
 * and a phone number.
 *
 */
emailAddress = findViewById(R.id.email)
phoneNumber = findViewById(R.id.phone)
...
/*
 * Inserts new data into the Intent. This data is passed to the
 * contacts app's Insert screen
 */
intent.apply {
    // Inserts an email address
    putExtra(ContactsContract.Intents.Insert.EMAIL, emailAddress?.text)
    /*
     * In this example, sets the email type to be a work email.
     * You can set other email types as necessary.
     */
    putExtra(
            ContactsContract.Intents.Insert.EMAIL_TYPE,
            ContactsContract.CommonDataKinds.Email.TYPE_WORK
    )
    // Inserts a phone number
    putExtra(ContactsContract.Intents.Insert.PHONE, phoneNumber?.text)
    /*
     * In this example, sets the phone type to be a work phone.
     * You can set other phone types as necessary.
     */
    putExtra(
            ContactsContract.Intents.Insert.PHONE_TYPE,
            ContactsContract.CommonDataKinds.Phone.TYPE_WORK
    )
}

جاوا

private EditText emailAddress = null;
private EditText phoneNumber = null;
...
/* Assumes EditText fields in your UI contain an email address
 * and a phone number.
 *
 */
emailAddress = (EditText) findViewById(R.id.email);
phoneNumber = (EditText) findViewById(R.id.phone);
...
/*
 * Inserts new data into the Intent. This data is passed to the
 * contacts app's Insert screen
 */
// Inserts an email address
intent.putExtra(ContactsContract.Intents.Insert.EMAIL, emailAddress.getText())
/*
 * In this example, sets the email type to be a work email.
 * You can set other email types as necessary.
 */
      .putExtra(ContactsContract.Intents.Insert.EMAIL_TYPE,
            ContactsContract.CommonDataKinds.Email.TYPE_WORK)
// Inserts a phone number
      .putExtra(ContactsContract.Intents.Insert.PHONE, phoneNumber.getText())
/*
 * In this example, sets the phone type to be a work phone.
 * You can set other phone types as necessary.
 */
      .putExtra(ContactsContract.Intents.Insert.PHONE_TYPE,
            ContactsContract.CommonDataKinds.Phone.TYPE_WORK);

هنگامی که Intent را ایجاد کردید، آن را با فراخوانی startActivity() ارسال کنید.

کاتلین

    /* Sends the Intent
     */
    startActivity(intent)

جاوا

    /* Sends the Intent
     */
    startActivity(intent);

این تماس صفحه ای را در برنامه مخاطبین باز می کند که به کاربران اجازه می دهد مخاطب جدیدی را وارد کنند. نوع حساب و نام حساب برای مخاطب در بالای صفحه نمایش داده شده است. هنگامی که کاربران داده ها را وارد کردند و روی انجام شد کلیک کردند، لیست مخاطبین برنامه مخاطبین ظاهر می شود. کاربران با کلیک کردن بر برگشت به برنامه شما باز می گردند.

یک مخاطب موجود را با استفاده از intent ویرایش کنید

ویرایش یک مخاطب موجود با استفاده از Intent در صورتی مفید است که کاربر قبلاً مخاطب مورد علاقه خود را انتخاب کرده باشد. برای مثال، برنامه‌ای که مخاطبینی را پیدا می‌کند که دارای آدرس پستی هستند اما فاقد کد پستی هستند، می‌تواند به کاربران این امکان را بدهد که کد را جستجو کرده و سپس آن را به مخاطب اضافه کنند.

برای ویرایش یک مخاطب موجود با استفاده از intent، از روشی مشابه درج یک مخاطب استفاده کنید. یک intent همانطور که در بخش توضیح داده شد ایجاد کنید . یک مخاطب جدید با استفاده از intent وارد کنید ، اما Contacts.CONTENT_LOOKUP_URI و نوع MIME Contacts.CONTENT_ITEM_TYPE را به intent اضافه کنید. اگر می خواهید مخاطب را با جزئیاتی که از قبل دارید ویرایش کنید، می توانید آنها را در داده های توسعه یافته intent قرار دهید. توجه داشته باشید که برخی از ستون‌های نام را نمی‌توان با استفاده از intent ویرایش کرد. این ستون ها در بخش خلاصه مرجع API برای کلاس ContactsContract.Contacts تحت عنوان "Update" فهرست شده اند.

در نهایت، قصد ارسال کنید. در پاسخ، برنامه مخاطبین صفحه ویرایش را نشان می دهد. وقتی کاربر ویرایش را تمام کرد و ویرایش ها را ذخیره کرد، برنامه مخاطبین لیست مخاطبین را نمایش می دهد. وقتی کاربر بر برگشت کلیک می کند، برنامه شما نمایش داده می شود.

قصد ایجاد کنید

برای ویرایش مخاطب، Intent(action) را فراخوانی کنید تا با عمل ACTION_EDIT یک intent ایجاد کنید. با فراخوانی setDataAndType() مقدار داده را برای intent روی Contacts.CONTENT_LOOKUP_URI و نوع MIME را روی Contacts.CONTENT_ITEM_TYPE نوع MIME تنظیم کنید. از آنجایی که فراخوانی به setType() مقدار داده فعلی را برای Intent بازنویسی می کند، باید داده ها و نوع MIME را همزمان تنظیم کنید.

برای دریافت Contacts.CONTENT_LOOKUP_URI یک مخاطب، Contacts.getLookupUri(id, lookupkey) را با مقادیر Contacts._ID و Contacts.LOOKUP_KEY مخاطب به عنوان آرگومان تماس بگیرید.

توجه: مقدار LOOKUP_KEY یک مخاطب، شناسه‌ای است که باید برای بازیابی مخاطب از آن استفاده کنید. ثابت می ماند، حتی اگر ارائه دهنده شناسه ردیف مخاطب را برای انجام عملیات داخلی تغییر دهد.

قطعه زیر به شما نشان می دهد که چگونه یک intent ایجاد کنید:

کاتلین

    // The Cursor that contains the Contact row
    var mCursor: Cursor? = null
    // The index of the lookup key column in the cursor
    var lookupKeyIndex: Int = 0
    // The index of the contact's _ID value
    var idIndex: Int = 0
    // The lookup key from the Cursor
    var currentLookupKey: String? = null
    // The _ID value from the Cursor
    var currentId: Long = 0
    // A content URI pointing to the contact
    var selectedContactUri: Uri? = null
    ...
    /*
     * Once the user has selected a contact to edit,
     * this gets the contact's lookup key and _ID values from the
     * cursor and creates the necessary URI.
     */
    mCursor?.apply {
        // Gets the lookup key column index
        lookupKeyIndex = getColumnIndex(ContactsContract.Contacts.LOOKUP_KEY)
        // Gets the lookup key value
        currentLookupKey = getString(lookupKeyIndex)
        // Gets the _ID column index
        idIndex = getColumnIndex(ContactsContract.Contacts._ID)
        currentId = getLong(idIndex)
        selectedContactUri = ContactsContract.Contacts.getLookupUri(currentId, mCurrentLookupKey)
    }

    // Creates a new Intent to edit a contact
    val editIntent = Intent(Intent.ACTION_EDIT).apply {
        /*
         * Sets the contact URI to edit, and the data type that the
         * Intent must match
         */
        setDataAndType(selectedContactUri, ContactsContract.Contacts.CONTENT_ITEM_TYPE)
    }

جاوا

    // The Cursor that contains the Contact row
    public Cursor mCursor;
    // The index of the lookup key column in the cursor
    public int lookupKeyIndex;
    // The index of the contact's _ID value
    public int idIndex;
    // The lookup key from the Cursor
    public String currentLookupKey;
    // The _ID value from the Cursor
    public long currentId;
    // A content URI pointing to the contact
    Uri selectedContactUri;
    ...
    /*
     * Once the user has selected a contact to edit,
     * this gets the contact's lookup key and _ID values from the
     * cursor and creates the necessary URI.
     */
    // Gets the lookup key column index
    lookupKeyIndex = mCursor.getColumnIndex(ContactsContract.Contacts.LOOKUP_KEY);
    // Gets the lookup key value
    currentLookupKey = mCursor.getString(lookupKeyIndex);
    // Gets the _ID column index
    idIndex = mCursor.getColumnIndex(ContactsContract.Contacts._ID);
    currentId = mCursor.getLong(idIndex);
    selectedContactUri =
            Contacts.getLookupUri(currentId, mCurrentLookupKey);
    ...
    // Creates a new Intent to edit a contact
    Intent editIntent = new Intent(Intent.ACTION_EDIT);
    /*
     * Sets the contact URI to edit, and the data type that the
     * Intent must match
     */
    editIntent.setDataAndType(selectedContactUri, ContactsContract.Contacts.CONTENT_ITEM_TYPE);

پرچم ناوبری را اضافه کنید

در اندروید 4.0 (API نسخه 14) و جدیدتر، مشکلی در برنامه مخاطبین باعث ناوبری نادرست می شود. وقتی برنامه شما قصد ویرایش را به برنامه مخاطبین ارسال می‌کند و کاربران یک مخاطب را ویرایش و ذخیره می‌کنند، وقتی روی برگشت کلیک می‌کنند صفحه فهرست مخاطبین را می‌بینند. برای بازگشت به برنامه شما، آنها باید روی Recents کلیک کرده و برنامه شما را انتخاب کنند.

برای حل این مشکل در Android نسخه 4.0.3 (API نسخه 15) و جدیدتر، کلید داده توسعه یافته finishActivityOnSaveCompleted با مقدار true به intent اضافه کنید. نسخه های اندروید قبل از اندروید 4.0 این کلید را می پذیرند، اما تاثیری ندارد. برای تنظیم داده های توسعه یافته، موارد زیر را انجام دهید:

کاتلین

    // Sets the special extended data for navigation
    editIntent.putExtra("finishActivityOnSaveCompleted", true)

جاوا

    // Sets the special extended data for navigation
    editIntent.putExtra("finishActivityOnSaveCompleted", true);

داده های توسعه یافته دیگر را اضافه کنید

برای افزودن داده های توسعه یافته اضافی به Intent ، به دلخواه putExtra() فراخوانی کنید. می‌توانید با استفاده از مقادیر کلیدی مشخص‌شده در Intents.Insert ، داده‌های توسعه‌یافته را برای فیلدهای مخاطب مشترک اضافه کنید. به یاد داشته باشید که برخی از ستون ها در جدول ContactsContract.Contacts قابل تغییر نیستند. این ستون ها در بخش خلاصه مرجع API برای کلاس ContactsContract.Contacts تحت عنوان "به روز رسانی" فهرست شده اند.

نیت را ارسال کنید

در نهایت، هدفی را که ساخته اید ارسال کنید. به عنوان مثال:

کاتلین

    // Sends the Intent
    startActivity(editIntent)

جاوا

    // Sends the Intent
    startActivity(editIntent);

به کاربران اجازه دهید با استفاده از یک intent درج یا ویرایش کنند

می‌توانید با ارسال یک Intent با عملکرد ACTION_INSERT_OR_EDIT ، به کاربران اجازه دهید انتخاب کنند که آیا یک مخاطب را وارد کنند یا یک مخاطب موجود را ویرایش کنند. به عنوان مثال، یک برنامه سرویس گیرنده ایمیل می تواند به کاربران اجازه دهد یک آدرس ایمیل دریافتی را به یک مخاطب جدید اضافه کنند، یا آن را به عنوان یک آدرس اضافی برای یک مخاطب موجود اضافه کنند. نوع MIME را برای این هدف روی Contacts.CONTENT_ITEM_TYPE تنظیم کنید، اما URI داده را تنظیم نکنید.

هنگامی که این هدف را ارسال می کنید، برنامه مخاطبین لیستی از مخاطبین را نمایش می دهد. کاربران می توانند یک مخاطب جدید وارد کنند یا یک مخاطب موجود را انتخاب کرده و آن را ویرایش کنند. هر فیلد داده گسترده ای که به intent اضافه کنید صفحه نمایش داده شده را پر می کند. می توانید از هر یک از مقادیر کلیدی مشخص شده در Intents.Insert استفاده کنید. قطعه کد زیر نحوه ساخت و ارسال intent را نشان می دهد:

کاتلین

    // Creates a new Intent to insert or edit a contact
    val intentInsertEdit = Intent(Intent.ACTION_INSERT_OR_EDIT).apply {
        // Sets the MIME type
        type = ContactsContract.Contacts.CONTENT_ITEM_TYPE
    }
    // Add code here to insert extended data, if desired

    // Sends the Intent with an request ID
    startActivity(intentInsertEdit)

جاوا

    // Creates a new Intent to insert or edit a contact
    Intent intentInsertEdit = new Intent(Intent.ACTION_INSERT_OR_EDIT);
    // Sets the MIME type
    intentInsertEdit.setType(ContactsContract.Contacts.CONTENT_ITEM_TYPE);
    // Add code here to insert extended data, if desired
    ...
    // Sends the Intent with an request ID
    startActivity(intentInsertEdit);