Kontakte mithilfe von Intents ändern

In dieser Lektion erfahren Sie, wie Sie mit einem Intent einen neuen Kontakt einfügen oder die Daten eines Kontakts ändern. Anstatt direkt auf den Kontaktdatenanbieter zuzugreifen, startet eine Intent die Kontakte App, die die entsprechende Activity ausführt. Wenn Sie bei den in dieser Lektion beschriebenen Änderungsaktionen erweiterte Daten mit der Intent senden, werden diese in die UI der gestarteten Activity eingegeben.

Die Verwendung eines Intent zum Einfügen oder Aktualisieren eines einzelnen Kontakts ist aus den folgenden Gründen die bevorzugte Methode zum Ändern des Kontaktanbieters:

• Sie sparen Zeit und Mühe bei der Entwicklung Ihrer eigenen Benutzeroberfläche und Ihres eigenen Codes.
• So werden Fehler vermieden, die durch Änderungen verursacht werden, die nicht den Regeln des Kontaktdatenanbieters entsprechen.
• So müssen Sie weniger Berechtigungen anfordern. Ihre App benötigt keine Berechtigung zum Schreiben in den Contacts Provider, da sie Änderungen an der Kontakte-App delegiert, die diese Berechtigung bereits hat.

Neuen Kontakt mithilfe eines Intents einfügen

Sie möchten dem Nutzer oft erlauben, einen neuen Kontakt einzufügen, wenn Ihre App neue Daten erhält. So können Nutzer in einer App für Restaurantbewertungen beispielsweise das Restaurant als Kontakt hinzufügen, während sie eine Rezension verfassen. Wenn Sie dies mit einem Intent tun möchten, erstellen Sie den Intent mit so vielen Daten wie verfügbar und senden Sie ihn dann an die Kontakte App.

Wenn Sie einen Kontakt über die Kontakte App einfügen, wird ein neuer roher Kontakt in die Tabelle ContactsContract.RawContacts des Kontaktdatenanbieters eingefügt. Falls erforderlich, werden Nutzer in der Kontakte App aufgefordert, den Kontotyp und das Konto anzugeben, das beim Erstellen des Rohkontakts verwendet werden soll. Die Kontakte App benachrichtigt Nutzer auch, wenn der Rohkontakt bereits vorhanden ist. Nutzer können die Einfügung dann abbrechen. In diesem Fall wird kein Kontakt erstellt. Weitere Informationen zu Rohkontakten finden Sie im API-Leitfaden für den Kontaktanbieter.

Intent erstellen

Erstellen Sie zuerst ein neues Intent-Objekt mit der Aktion Intents.Insert.ACTION. Legen Sie als MIME-Typ RawContacts.CONTENT_TYPE fest. Beispiel:

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

Wenn Sie bereits Details für den Kontakt haben, z. B. eine Telefonnummer oder E-Mail-Adresse, können Sie diese als erweiterte Daten in die Intent-Definition einfügen. Verwenden Sie für einen Schlüsselwert die entsprechende Konstante aus Intents.Insert. Die Kontakt-App zeigt die Daten auf dem Einfügebildschirm an, sodass Nutzer weitere Änderungen und Ergänzungen vornehmen können.

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

Nachdem du die Intent erstellt hast, kannst du sie senden, indem du startActivity() aufrufst.

    /* Sends the Intent
     */
    startActivity(intent)

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

Bei diesem Anruf wird in der Kontakte App ein Bildschirm geöffnet, auf dem Nutzer einen neuen Kontakt eingeben können. Der Kontotyp und der Kontoname des Kontakts werden oben auf dem Bildschirm angezeigt. Sobald Nutzer die Daten eingegeben und auf Fertig geklickt haben, wird die Kontaktliste der Kontakt-App angezeigt. Nutzer können mit Zurück zu Ihrer App zurückkehren.

Vorhandenen Kontakt mithilfe eines Intents bearbeiten

Das Bearbeiten eines vorhandenen Kontakts mithilfe eines Intent ist hilfreich, wenn der Nutzer bereits einen Kontakt ausgewählt hat. Eine App, die beispielsweise Kontakte mit einer Postanschrift, aber ohne Postleitzahl findet, könnte Nutzern die Möglichkeit bieten, die Postleitzahl nachzuschlagen und sie dann dem Kontakt hinzuzufügen.

Wenn Sie einen vorhandenen Kontakt mithilfe eines Intents bearbeiten möchten, gehen Sie ähnlich vor wie beim Einfügen eines Kontakts. Erstellen Sie eine Intent wie im Abschnitt Neuen Kontakt mit einer Intent-Aktion einfügen beschrieben, fügen Sie der Intent aber die Contacts.CONTENT_LOOKUP_URI des Kontakts und den MIME-Typ Contacts.CONTENT_ITEM_TYPE hinzu. Wenn Sie den Kontakt mit bereits vorhandenen Details bearbeiten möchten, können Sie diese in die erweiterten Daten der Absicht einfügen. Einige Spalten mit Namen können nicht mithilfe eines Intents bearbeitet werden. Diese Spalten sind in der API-Referenz für die Klasse ContactsContract.Contacts im Abschnitt „Zusammenfassung“ unter der Überschrift „Aktualisieren“ aufgeführt.

Senden Sie abschließend den Intent. Daraufhin wird in der Kontakte App ein Bearbeitungsbildschirm angezeigt. Wenn der Nutzer die Bearbeitung abgeschlossen und die Änderungen gespeichert hat, zeigt die Kontakt-App eine Kontaktliste an. Wenn der Nutzer auf Zurück klickt, wird Ihre App angezeigt.

Intent erstellen

Wenn Sie einen Kontakt bearbeiten möchten, rufen Sie Intent(action) auf, um einen Intent mit der Aktion ACTION_EDIT zu erstellen. Rufen Sie setDataAndType() auf, um den Datenwert für die Absicht auf den Contacts.CONTENT_LOOKUP_URI des Kontakts und den MIME-Typ auf Contacts.CONTENT_ITEM_TYPE festzulegen. Da ein Aufruf von setType() den aktuellen Datenwert für die Intent überschreibt, müssen Sie die Daten und den MIME-Typ gleichzeitig festlegen.

Wenn Sie die Contacts.CONTENT_LOOKUP_URI eines Kontakts abrufen möchten, rufen Sie Contacts.getLookupUri(id, lookupkey) mit den Werten Contacts._ID und Contacts.LOOKUP_KEY des Kontakts als Argumente auf.

Hinweis:Der LOOKUP_KEY-Wert eines Kontakts ist die Kennung, die Sie zum Abrufen eines Kontakts verwenden sollten. Sie bleibt konstant, auch wenn der Anbieter die Zeilen-ID des Kontakts für interne Vorgänge ändert.

Im folgenden Snippet wird gezeigt, wie ein Intent erstellt wird:

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

Navigations-Flag hinzufügen

Unter Android 4.0 (API-Version 14) und höher führt ein Problem in der Kontakte App zu einer falschen Navigation. Wenn Ihre App eine Bearbeitungsabsicht an die Kontakte App sendet und Nutzer einen Kontakt bearbeiten und speichern, wird beim Klicken auf Zurück der Bildschirm mit der Kontaktliste angezeigt. Wenn er zu Ihrer App zurückkehren möchte, muss er auf Letzte klicken und Ihre App auswählen.

Um dieses Problem unter Android 4.0.3 (API-Version 15) und höher zu umgehen, fügen Sie dem Intent den erweiterten Datenschlüssel finishActivityOnSaveCompleted mit dem Wert true hinzu. Android-Versionen vor Android 4.0 akzeptieren diesen Schlüssel, er hat jedoch keine Auswirkungen. So legen Sie die erweiterten Daten fest:

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

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

Weitere erweiterte Daten hinzufügen

Wenn Sie dem Intent zusätzliche erweiterte Daten hinzufügen möchten, rufen Sie putExtra() auf. Sie können erweiterte Daten für gängige Kontaktdatenfelder hinzufügen, indem Sie die in Intents.Insert angegebenen Schlüsselwerte verwenden. Einige Spalten in der Tabelle ContactsContract.Contacts können nicht geändert werden. Diese Spalten sind im Zusammenfassungsbereich der API-Referenz für die KlasseContactsContract.Contacts unter der Überschrift „Update“ aufgeführt.

Intent senden

Senden Sie abschließend die von Ihnen erstellte Intent-Anfrage. Beispiel:

    // Sends the Intent
    startActivity(editIntent)

    // Sends the Intent
    startActivity(editIntent);

Nutzern die Möglichkeit geben, Inhalte mithilfe eines Intents einzufügen oder zu bearbeiten

Sie können Nutzern erlauben, auszuwählen, ob sie einen Kontakt einfügen oder einen vorhandenen bearbeiten möchten, indem Sie eine Intent mit der Aktion ACTION_INSERT_OR_EDIT senden. So kann eine E-Mail-Client-App Nutzern beispielsweise erlauben, einem neuen Kontakt eine E-Mail-Adresse für eingehende E-Mails hinzuzufügen oder sie als zusätzliche Adresse für einen vorhandenen Kontakt hinzuzufügen. Legen Sie den MIME-Typ für diese Absicht auf Contacts.CONTENT_ITEM_TYPE fest, aber nicht die Daten-URI.

Wenn Sie diesen Intent senden, zeigt die Kontakte-App eine Liste von Kontakten an. Die Nutzer können entweder einen neuen Kontakt einfügen oder einen vorhandenen Kontakt auswählen und bearbeiten. Alle erweiterten Datenfelder, die Sie der Intent-Anfrage hinzufügen, werden auf dem angezeigten Bildschirm angezeigt. Sie können einen der in Intents.Insert angegebenen Schlüsselwerte verwenden. Das folgende Code-Snippet zeigt, wie die Intent erstellt und gesendet wird:

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