تعديل جهات الاتصال باستخدام الأغراض

يوضّح لك هذا الدرس كيفية استخدام Intent لإدراج جهة اتصال جديدة أو تعديل بيانات جهة اتصال. بدلاً من الوصول إلى مقدّم جهات الاتصال مباشرةً، يبدأ Intent تطبيق جهات الاتصال الذي يشغّل Activity المناسب. وفيما يتعلق بإجراءات التعديل الموضحة في هذا الدرس، إذا أرسلت بيانات موسّعة في Intent، سيتم إدخالها في واجهة مستخدم Activity التي تم تشغيلها.

من المفضّل استخدام Intent لإدراج جهة اتصال واحدة أو تعديلها. لتعديل "موفر جهات الاتصال"، للأسباب التالية:

• فهو يوفّر عليك الوقت والجهد المبذولَين في تطوير واجهة المستخدم والرموز البرمجية.
• يتجنب تقديم أخطاء ناجمة عن تعديلات لا تتبع قواعد موفّر جهات الاتصال.
• يقلل عدد الأذونات التي تحتاج إلى طلبها. لا يحتاج تطبيقك إلى إذن للكتابة في مقدّم جهات الاتصال، لأنّه يفوّض التعديلات إلى تطبيق جهات الاتصال، الذي يملك هذا الإذن من قبل.

إدراج جهة اتصال جديدة باستخدام هدف

غالبًا ما تريد السماح للمستخدم بإدخال جهة اتصال جديدة عندما يتلقّى تطبيقك بيانات جديدة. على سبيل المثال، يمكن أن يسمح تطبيق مراجعات المطاعم للمستخدمين بإضافة المطعم كجهة اتصال أثناء إجراء المراجعة. ولإجراء ذلك باستخدام هدف، أنشِئه باستخدام أكبر قدر ممكن من البيانات لديك. ثم إرسال intent إلى تطبيق جهات الاتصال.

يؤدي إدراج جهة اتصال باستخدام تطبيق جهات الاتصال إلى إدراج جهة اتصال أولية جديدة في جدول ContactsContract.RawContacts الخاص بموفِّر جهات الاتصال . إذا لزم الأمر، يطلب تطبيق جهات الاتصال من المستخدمين نوع الحساب والحساب لاستخدامهما عند إنشاء البيانات الأولية جهة اتصال. ويُرسِل تطبيق جهات الاتصال أيضًا إشعارًا إلى المستخدمين إذا كانت جهة الاتصال الأولية متوفّرة من قبل. بعد ذلك، حصل المستخدمون على خيار إلغاء الإدراج، وفي هذه الحالة لا يتم إنشاء جهة اتصال. للتعلّم المزيد حول جهات الاتصال الأولية، راجع مزوِّد جهات الاتصال دليل واجهة برمجة التطبيقات.

إنشاء نية

للبدء، أنشئ عنصرًا جديدًا من النوع 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);

إذا كان لديك تفاصيل لجهة الاتصال، مثل رقم هاتف أو عنوان بريد إلكتروني، يمكنك وإدراجها في المقصد كبيانات موسعة. للحصول على قيمة رئيسية، استخدم الثابت المناسب من 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 مفيدًا إذا كان المستخدم قد اختار جهة اتصال تهمّه. على سبيل المثال، أحد التطبيقات التي يعثر على جهات الاتصال التي تحتوي عناوين بريدية ولكن تفتقر إلى رمز بريدي إلى أن تمنح المستخدمين خيار البحث عن الرمز ثم إضافته إلى جهة الاتصال.

لتعديل جهة اتصال حالية باستخدام هدف، استخدِم إجراءً مشابهًا إدراج جهة اتصال. أنشئ نية كما هو موضّح في القسم إدراج جهة اتصال جديدة باستخدام نية، ولكن أضِف Contacts.CONTENT_LOOKUP_URI جهة الاتصال وContacts.CONTENT_ITEM_TYPE نوع MIME إلى النية. إذا أردت تعديل جهة الاتصال من خلال تقديم تفاصيل يمكنك وضعها بالفعل في البيانات الموسّعة الخاصة بالهدف. لاحظ أن بعض لا يمكن تعديل أعمدة الأسماء باستخدام إجراء. يتم سرد هذه الأعمدة في ملخص في مرجع واجهة برمجة التطبيقات للفئة ContactsContract.Contacts تحت العنوان "تحديث".

أخيرًا، أرسل النية. وفي ردّ على ذلك، يعرض تطبيق جهات الاتصال شاشة تعديل. عندما يجرّب ينتهي التعديل ويحفظ التعديلات، سيعرض تطبيق جهات الاتصال قائمة جهات اتصال. عندما ينقر المستخدم على رجوع، يتم عرض تطبيقك.

إنشاء النية

لتعديل جهة اتصال، اتّصِل بـ Intent(action) من أجل إنشاء مقصد من خلال الإجراء ACTION_EDIT. اتصل بـ setDataAndType() لضبط قيمة البيانات لمحاولة العميل للتواصل على 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 لجهة الاتصال هي المعرّف الذي يجب استخدامه لاسترداد جهة اتصال. ويظلّ هذا المعرّف ثابتًا، حتى إذا غيّر مقدّم الخدمة معرّف صف جهة الاتصال لمعالجة العمليات الداخلية.

يوضّح لك المقتطف التالي كيفية إنشاء نية:

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

إضافة علامة التنقّل

في Android 4.0 (الإصدار 14 من واجهة برمجة التطبيقات) والإصدارات الأحدث، تؤدي مشكلة في تطبيق جهات الاتصال إلى حدوث خطأ التنقل. عندما يرسل تطبيقك طلب تعديل إلى تطبيق جهات الاتصال، ويُعدِّل المستخدمون جهة اتصال ويحفظونها، تظهر لهم شاشة قائمة جهات الاتصال عند النقر على رجوع. للرجوع إلى تطبيقك، سيضطر إلى النقر على التطبيقات الأخيرة واختيار تطبيقك.

للتغلب على هذه المشكلة في Android 4.0.3 (واجهة برمجة التطبيقات الإصدار 15) والإصدارات الأحدث، أضف مفتاح البيانات finishActivityOnSaveCompleted إلى الغرض، بقيمة true. وتقبل إصدارات Android التي تسبق الإصدار Android 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. يتم إدراج هذه الأعمدة في قسم الملخّص من مرجع واجهة برمجة التطبيقات للصف يليه ContactsContract.Contacts ضمن العنوان "تعديل".

إرسال الهدف

وأخيرًا، أرسل الهدف الذي أنشأته. مثلاً:

    // Sends the Intent
    startActivity(editIntent)

    // Sends the Intent
    startActivity(editIntent);

السماح للمستخدمين باختيار إدراج المحتوى أو تعديله باستخدام نية

يمكنك السماح للمستخدمين باختيار ما إذا كانوا يريدون إدراج جهة اتصال أو تعديل جهة اتصال حالية من خلال إرسال Intent مع الإجراء ACTION_INSERT_OR_EDIT. على سبيل المثال، يمكن لتطبيق برنامج بريد إلكتروني السماح للمستخدمين بإضافة عنوان بريد إلكتروني وارد إلى جهة اتصال جديدة، أو إضافته كعنوان إضافي لجهة اتصال حالية. اضبط نوع MIME لهذا الطلب على Contacts.CONTENT_ITEM_TYPE، ولكن لا تضبط معرّف الموارد المنتظم (URI) للبيانات.

عند إرسال رسالة الغرض هذه، يعرض تطبيق جهات الاتصال قائمة بجهات الاتصال. يمكن للمستخدمين إدراج جهة اتصال جديدة أو اختيار جهة اتصال حالية وتعديلها. تتم تعبئة الشاشة التي تظهر إذا كانت أي حقول بيانات موسّعة تضيفها إلى الغرض. يمكنك استخدام أيّ من قيم المفاتيح المحدّدة في Intents.Insert. يوضّح المقتطف البرمجي التالي كيفية إنشاء النية وإرسالها:

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