Niyetleri kullanarak kişileri değiştirme

Bu derste, yeni bir kişi eklemek veya bir kişinin verilerini değiştirmek için Intent aracının nasıl kullanılacağı gösterilmektedir. Intent, doğrudan Kişi Sağlayıcı'ya erişmek yerine uygun Activity uygulamasını çalıştıran kişiler uygulamasını başlatır. Bu derste açıklanan değişiklik işlemleri için Intent aracında genişletilmiş veriler gönderirseniz bu veriler başlatılan Activity arayüzünün kullanıcı arayüzüne girilir.

Aşağıdaki nedenlerden dolayı Kişi Sağlayıcı değişikliği için tercih edilen yöntem, tek bir kişi eklemek veya güncellemek için Intent kullanılmasıdır:

• Kendi kullanıcı arayüzünüzü ve kodunuzu geliştirmek için harcadığınız zamandan ve emekten tasarruf etmenizi sağlar.
• Kişi Sağlayıcısının kurallarına uymayan değişikliklerin neden olduğu hataların ortaya çıkmasını önler.
• Bu, istemeniz gereken izin sayısını azaltır. Uygulamanızın, Kişi Sağlayıcı'ya yazmak için izne ihtiyacı yoktur, çünkü zaten ilgili izne sahip olan kişiler uygulamasında yapılan değişiklikler için yetki verir.

Niyet kullanarak yeni kişi ekleme

Genellikle uygulamanız yeni veri aldığında kullanıcının yeni kişi eklemesine izin vermek istersiniz. Örneğin, bir restoran incelemesi uygulaması, kullanıcıların restoranı inceleyen bir kişi olarak restoranı eklemelerine izin verebilir. Bunu bir intent kullanarak yapmak için elinizdeki olabildiğince çok veri kullanarak amacı oluşturun ve ardından amacı kişiler uygulamasına gönderin.

Kişiler uygulamasını kullanarak kişi eklendiğinde, Kişi Sağlayıcı'nın ContactsContract.RawContacts tablosuna yeni bir ham kişi eklenir. Kişiler uygulaması gerekirse ham kişi oluştururken kullanıcılardan hesap türü ve hesabı kullanmalarını ister. Kişiler uygulaması, ham kişi zaten varsa kullanıcıları da bilgilendirir. Kullanıcılar daha sonra ekleme işlemini iptal edebilir. Bu durumda herhangi bir kişi oluşturulmaz. Ham kişiler hakkında daha fazla bilgi edinmek için Contacts Sağlayıcı API kılavuzuna bakın.

Amaç oluşturma

Başlamak için Intents.Insert.ACTION işlemiyle yeni bir Intent nesnesi oluşturun. MIME türünü RawContacts.CONTENT_TYPE olarak ayarlayın. Örnek:

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

Kişiyle ilgili zaten bilgilere sahipseniz (ör. telefon numarası veya e-posta adresi) bu ayrıntıları amaca genişletilmiş veri olarak ekleyebilirsiniz. Bir anahtar değeri için Intents.Insert değerlerinden uygun sabit değeri kullanın. Kişiler uygulaması, verileri ekleme ekranında görüntüleyerek kullanıcıların daha fazla düzenleme ve ekleme yapmalarına olanak tanır.

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 oluşturduktan sonra startActivity() numaralı telefonu arayarak gönderin.

    /* Sends the Intent
     */
    startActivity(intent)

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

Bu görüşme, kişiler uygulamasında kullanıcıların yeni kişi girmelerine olanak tanıyan bir ekran açar. Kişinin hesap türü ve hesap adı ekranın üst kısmında listelenir. Kullanıcılar verileri girip Bitti'yi tıkladıktan sonra, kişiler uygulamasının kişi listesi görünür. Kullanıcılar Geri'yi tıklayarak uygulamanıza geri döner.

Intent kullanarak mevcut kişileri düzenleme

Kullanıcı, ilgilenecek bir kişiyi zaten seçmişse Intent kullanarak mevcut bir kişiyi düzenlemek faydalı olur. Örneğin, posta adresleri olan ancak posta kodu eksik olan kişileri bulan bir uygulama, kullanıcılara kodu arayıp kişiye ekleme seçeneği sunabilir.

Mevcut bir kişiyi bir amaç kullanarak düzenlemek için kişi eklemeye benzer bir prosedür kullanın. Amaç kullanarak yeni bir kişi ekleme bölümünde açıklandığı gibi bir amaç oluşturun. Ancak niyete kişinin Contacts.CONTENT_LOOKUP_URI ve MIME türü Contacts.CONTENT_ITEM_TYPE ekleyin. Kişiyi elinizdeki ayrıntılarla düzenlemek istiyorsanız bu bilgileri amacın genişletilmiş verilerine ekleyebilirsiniz. Bazı ad sütunlarının bir amaç kullanılarak düzenlenemeyeceğini unutmayın. Bu sütunlar, ContactsContract.Contacts sınıfının API referansının özet bölümünde, "Güncelle" başlığı altında listelenmiştir.

Son olarak amacı gönderin. Buna yanıt olarak, kişiler uygulaması bir düzenleme ekranı gösterir. Kullanıcı düzenlemeyi bitirip düzenlemeleri kaydettikten sonra, kişiler uygulaması bir kişi listesi görüntüler. Kullanıcı Geri'yi tıkladığında uygulamanız görüntülenir.

Amacı oluşturma

Bir kişiyi düzenlemek için ACTION_EDIT işlemiyle bir amaç oluşturmak üzere Intent(action) adlı kişiyi arayın. Niyetin veri değerini kişinin Contacts.CONTENT_LOOKUP_URI ve MIME türünü Contacts.CONTENT_ITEM_TYPE MIME türü olarak ayarlamak için setDataAndType() yöntemini çağırın. setType() çağrısı Intent için geçerli veri değerinin üzerine yazdığından verileri ve MIME türünü aynı anda ayarlamanız gerekir.

Bir kişinin Contacts.CONTENT_LOOKUP_URI bilgisini almak için kişinin Contacts._ID ve Contacts.LOOKUP_KEY değerlerini bağımsız değişken olarak kullanarak Contacts.getLookupUri(id, lookupkey) çağrısı yapın.

Not: Bir kişinin LOOKUP_KEY değeri, bir kişiyi geri almak için kullanmanız gereken tanımlayıcıdır. Sağlayıcı, dahili işlemleri yönetmek için kişinin satır kimliğini değiştirse bile sabit kalır.

Aşağıdaki snippet'te intent'in nasıl oluşturulacağı gösterilmektedir:

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

Gezinme işaretini ekleme

Android 4.0 (API sürümü 14) ve sonraki sürümlerde kişiler uygulamasındaki bir sorun yanlış gezinmeye neden oluyor. Uygulamanız, kişiler uygulamasına bir düzenleme amacı gönderdiğinde ve kullanıcılar bir kişiyi düzenleyip kaydettiğinde Geri'yi tıkladıklarında kişi listesi ekranını görürler. Uygulamanıza geri gitmek için Son aramalar'ı tıklayıp uygulamanızı seçmeleri gerekir.

Android 4.0.3 (API sürümü 15) ve sonraki sürümlerde bu sorunu çözmek için genişletilmiş veri anahtarını finishActivityOnSaveCompleted adlı amaca true değeriyle ekleyin. Android 4.0'dan önceki Android sürümleri bu anahtarı kabul eder, ancak herhangi bir etkisi yoktur. Genişletilmiş verileri ayarlamak için aşağıdakileri yapın:

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

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

Başka genişletilmiş veriler ekleme

Intent öğesine genişletilmiş ek veriler eklemek için putExtra() numaralı telefonu arayın. Intents.Insert özelliğinde belirtilen anahtar değerlerini kullanarak ortak kişi alanları için genişletilmiş verileri ekleyebilirsiniz. ContactsContract.Contacts tablosundaki bazı sütunların değiştirilemeyeceğini unutmayın. Bu sütunlar, ContactsContract.Contacts sınıfının API referansının özet bölümünde "Güncelle" başlığı altında listelenir.

Amacı gönderin

Son olarak oluşturduğunuz amacı gönderin. Örnek:

    // Sends the Intent
    startActivity(editIntent)

    // Sends the Intent
    startActivity(editIntent);

Kullanıcıların bir amaç kullanarak ekleme veya düzenleme işlemi yapmasına izin ver

ACTION_INSERT_OR_EDIT işlemiyle bir Intent göndererek kullanıcıların kişi ekleme veya mevcut bir kişiyi düzenleme konusunda seçim yapmasına izin verebilirsiniz. Örneğin, bir e-posta istemcisi uygulaması, kullanıcıların gelen e-posta adresini yeni bir kişiye veya mevcut bir kişinin ek adresi olarak eklemesine olanak tanıyabilir. Bu amacın MIME türünü Contacts.CONTENT_ITEM_TYPE olarak ayarlayın ancak veri URI'sini ayarlamayın.

Bu amacı gönderdiğinizde kişiler uygulaması bir kişi listesi gösterir. Kullanıcılar yeni bir kişi ekleyebilir veya mevcut bir kişiyi seçip düzenleyebilir. Niyete eklediğiniz genişletilmiş veri alanları, görünen ekranı doldurur. Intents.Insert politikasında belirtilen anahtar/değer çiftlerini kullanabilirsiniz. Aşağıdaki kod snippet'inde amacın nasıl oluşturulacağı ve gönderileceği gösterilmektedir:

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