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

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

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

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

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

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

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

إنشاء نية

للبدء، أنشِئ كائن Intent جديدًا باستخدام الإجراء. Intents.Insert.ACTION اضبط نوع MIME على RawContacts.CONTENT_TYPE. مثلاً:

Kotlin

...
// 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
}

Java

...
// 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 تطبيق جهات الاتصال البيانات في شاشة الإدراج الخاصة بها، ما يتيح للمستخدمين إجراء المزيد من التعديلات والإضافات.

Kotlin

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

Java

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().

Kotlin

    /* Sends the Intent
     */
    startActivity(intent)

Java

    /* 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 هي بالمعرف الذي يجب استخدامه لاسترداد جهة اتصال. ويظلّ هذا المعرّف ثابتًا، حتى إذا غيّر مقدّم الخدمة معرّف صف جهة الاتصال لمعالجة العمليات الداخلية.

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

Kotlin

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

Java

    // 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 من Android (الإصدار 14 من واجهة برمجة التطبيقات) والإصدارات الأحدث، تؤدي مشكلة في تطبيق جهات الاتصال إلى توجيه خاطئ. عندما يرسل تطبيقك نية التعديل إلى تطبيق "جهات الاتصال"، ويعدّل المستخدمون ويحفظون جهة الاتصال، عندما ينقر المستخدم على رجوع، ستظهر له شاشة قائمة جهات الاتصال. للرجوع إلى تطبيقك، عليه النقر على التطبيقات المستخدَمة مؤخرًا واختيار تطبيقك.

لحلّ هذه المشكلة في الإصدار 4.0.3 من Android (الإصدار 15 من واجهة برمجة التطبيقات) والإصدارات الأحدث، أضِف مفتاح بيانات ممتدًا finishActivityOnSaveCompleted إلى النية، مع القيمة true. وتقبل إصدارات Android التي تسبق الإصدار Android 4.0 هذا المفتاح، ولكن ليس له أي تأثير. لضبط البيانات الموسعة، قم بما يلي:

Kotlin

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

Java

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

إضافة بيانات موسّعة أخرى

لإضافة بيانات موسّعة إضافية إلى Intent، اتصل putExtra() حسب الحاجة. يمكنك إضافة بيانات موسّعة لحقول جهات الاتصال الشائعة باستخدام قيم المفاتيح المحدَّدة في Intents.Insert يُرجى العلم أنّه لا يمكن تعديل بعض الأعمدة في جدول ContactsContract.Contacts. تم سرد هذه الأعمدة في قسم الملخص في مرجع واجهة برمجة التطبيقات للفئة ContactsContract.Contacts تحت العنوان "تحديث".

إرسال الطلب

أخيرًا، أرسِل النية التي أنشأتها. مثلاً:

Kotlin

    // Sends the Intent
    startActivity(editIntent)

Java

    // Sends the Intent
    startActivity(editIntent);

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

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

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

Kotlin

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

Java

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