این درس به شما نشان می دهد که چگونه از یک 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);