يوضّح لك هذا الدرس كيفية استخدام 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);