Modificare i contatti utilizzando intent

Questa lezione mostra come utilizzare un Intent per inserire un nuovo contatto o modificare i dati di un contatto. Anziché accedere direttamente al Provider di contatti, un Intent avvia l'app Contatti, che esegue l'Activity appropriato. Per le azioni di modifica descritte in questa lezione, se invii dati estesi in Intent, questi vengono inseriti nell'interfaccia utente di Activity avviata.

L'utilizzo di un Intent per inserire o aggiornare un singolo contatto è il modo preferito per modificare il Provider di contatti per i seguenti motivi:

  • In questo modo, risparmi tempo e fatica per lo sviluppo della tua UI e del tuo codice.
  • In questo modo, si evita di introdurre errori causati da modifiche che non seguono le regole del Provider di contatti.
  • Riduce il numero di autorizzazioni che devi richiedere. La tua app non ha bisogno dell'autorizzazione per scrivere nel Provider di contatti, perché delega le modifiche all'app Contatti, che dispone già di questa autorizzazione.

Inserisci un nuovo contatto utilizzando un intent

Spesso vuoi consentire all'utente di inserire un nuovo contatto quando la tua app riceve nuovi dati. Ad esempio, un'app di recensioni di ristoranti può consentire agli utenti di aggiungere il ristorante come contatto mentre lo recensiscono. Per farlo utilizzando un intent, crea l'intent utilizzando tutti i dati a tua disposizione, quindi invialo all'app Contatti.

L'inserimento di un contatto tramite l'app Contatti inserisce un nuovo contatto non elaborato nella tabella ContactsContract.RawContacts del Provider di contatti. Se necessario, l'app Contatti chiede agli utenti il tipo di account e l'account da utilizzare per la creazione del contatto non elaborato. L'app Contatti avvisa inoltre gli utenti se il contatto non elaborato esiste già. Gli utenti hanno quindi la possibilità di annullare l'inserimento, nel qual caso non viene creato alcun contatto. Per scoprire di più sui contatti non elaborati, consulta la guida all'API Provider di contatti.

Crea un intent

Per iniziare, crea un nuovo oggetto Intent con l'azione Intents.Insert.ACTION. Imposta il tipo MIME su RawContacts.CONTENT_TYPE. Ad esempio:

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

Se hai già i dettagli del contatto, ad esempio un numero di telefono o un indirizzo email, puoi inserirli nell'intent come dati estesi. Per un valore chiave, utilizza la costante appropriata di Intents.Insert. L'app Contatti visualizza i dati nella schermata di inserimento, consentendo agli utenti di apportare ulteriori modifiche e aggiunte.

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

Dopo aver creato Intent, invialo chiamando startActivity().

Kotlin

    /* Sends the Intent
     */
    startActivity(intent)

Java

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

Questa chiamata apre una schermata nell'app Contatti che consente agli utenti di inserire un nuovo contatto. Il tipo di account e il nome dell'account per il contatto sono elencati nella parte superiore dello schermo. Una volta inseriti i dati e fatto clic su Fine, viene visualizzato l'elenco contatti dell'app Contatti. Gli utenti tornano alla tua app facendo clic su Indietro.

Modifica un contatto esistente utilizzando un intent

La modifica di un contatto esistente utilizzando un Intent è utile se l'utente ha già scelto un contatto di interesse. Ad esempio, un'app che trova i contatti che hanno indirizzi postali, ma non un codice postale, potrebbe offrire agli utenti la possibilità di cercare il codice e aggiungerlo al contatto.

Per modificare un contatto esistente utilizzando un intent, utilizza una procedura simile a quella per l'inserimento di un contatto. Crea un intent come descritto nella sezione Inserisci un nuovo contatto utilizzando un intent, ma aggiungi all'intent il Contacts.CONTENT_LOOKUP_URI del contatto e il tipo MIME Contacts.CONTENT_ITEM_TYPE. Se vuoi modificare il contatto con i dettagli che hai già, puoi inserirli nei dati estesi dell'intent. Tieni presente che alcune colonne dei nomi non possono essere modificate utilizzando un intent. Queste colonne sono elencate nella sezione di riepilogo del riferimento API per la classe ContactsContract.Contacts sotto l'intestazione "Aggiorna".

Infine, invia l'intent. In risposta, l'app Contatti mostra una schermata di modifica. Quando l'utente termina la modifica e salva le modifiche, l'app Contatti visualizza un elenco contatti. Quando l'utente fai clic su Indietro, viene visualizzata la tua app.

Crea l'intent

Per modificare un contatto, chiama Intent(action) per creare un intent con l'azione ACTION_EDIT. Chiama setDataAndType() per impostare il valore dei dati per l'intent su Contacts.CONTENT_LOOKUP_URI del contatto e il tipo MIME sul tipo MIME Contacts.CONTENT_ITEM_TYPE; poiché una chiamata a setType() sovrascrive il valore dei dati corrente per Intent, devi impostare i dati e il tipo MIME contemporaneamente.

Per ottenere il Contacts.CONTENT_LOOKUP_URI di un contatto, chiama Contacts.getLookupUri(id, lookupkey) con i valori Contacts._ID e Contacts.LOOKUP_KEY del contatto come argomenti.

Nota: il valore LOOKUP_KEY di un contatto è l'identificatore che devi utilizzare per recuperare un contatto. Rimane costante, anche se il provider modifica l'ID riga del contatto per gestire le operazioni interne.

Il seguente snippet mostra come creare un intent:

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

Aggiungi il flag di navigazione

In Android 4.0 (API versione 14) e versioni successive, un problema nell'app Contatti causa una navigazione errata. Quando l'app invia un intent di modifica all'app Contatti e gli utenti modificano e salvano un contatto, quando fanno clic su Indietro visualizzano la schermata dell'elenco contatti. Per tornare alla tua app, deve fare clic su Recenti e scegliere la tua app.

Per risolvere questo problema in Android 4.0.3 (API versione 15) e versioni successive, aggiungi all'intent la chiave dei dati estesi finishActivityOnSaveCompleted con un valore pari a true. Le versioni di Android precedenti ad Android 4.0 accettano questa chiave, ma non ha alcun effetto. Per impostare i dati estesi, procedi nel seguente modo:

Kotlin

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

Java

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

Aggiungi altri dati estesi

Per aggiungere altri dati estesi a Intent, chiama putExtra() in base alle esigenze. Puoi aggiungere dati estesi per i campi di contatto comuni utilizzando i valori chiave specificati in Intents.Insert. Ricorda che alcune colonne della tabella ContactsContract.Contacts non possono essere modificate. Queste colonne sono elencate nella sezione di riepilogo del riferimento API per la classe ContactsContract.Contacts sotto l'intestazione "Aggiorna".

Invia l'intent

Infine, invia l'intent che hai creato. Ad esempio:

Kotlin

    // Sends the Intent
    startActivity(editIntent)

Java

    // Sends the Intent
    startActivity(editIntent);

Consenti agli utenti di scegliere di inserire o modificare utilizzando un intent

Puoi consentire agli utenti di scegliere se inserire un contatto o modificarne uno esistente inviando un Intent con l'azione ACTION_INSERT_OR_EDIT. Ad esempio, un'app client di posta potrebbe consentire agli utenti di aggiungere un indirizzo email in arrivo a un nuovo contatto o di aggiungerlo come indirizzo aggiuntivo per un contatto esistente. Imposta il tipo MIME per questo intent su Contacts.CONTENT_ITEM_TYPE, ma non impostare l'URI dei dati.

Quando invii questo intent, l'app Contatti mostra un elenco di contatti. Gli utenti possono inserire un nuovo contatto o sceglierne uno esistente e modificarlo. Tutti i campi di dati estesi aggiunti all'intent compilano la schermata visualizzata. Puoi utilizzare uno qualsiasi dei valori chiave specificati in Intents.Insert. Il seguente snippet di codice mostra come creare e inviare l'intent:

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