Esta página foi traduzida pela API Cloud Translation.

Modificar contatos usando intents

Esta lição mostra como usar uma Intent para inserir um novo contato ou modificar os dados de um contato. Em vez de acessar o Provedor de contatos diretamente, uma Intent inicia o app Contatos, que executa a Activity apropriada. Para as ações de modificação descritas nesta lição, Se você enviar dados estendidos no Intent, eles serão inseridos na interface do Activity iniciado.

O uso de uma Intent para inserir ou atualizar um único contato é a melhor maneira de modificar o Provedor de contatos, pelos seguintes motivos:

Isso economiza o tempo e o esforço necessários para desenvolver sua IU e o código.
Evita a introdução de erros causados por modificações que não seguem as regras do Provedor de contatos.
Isso reduz o número de permissões que você precisa solicitar. Seu app não precisa de permissão para gravar no Provedor de contatos, porque delega modificações no app Contatos, que já tem essa permissão.

Inserir um novo contato usando uma intent

Em geral, você permite que o usuário insira um novo contato quando seu app recebe novos dados. Por exemplo, um app de avaliação de restaurantes pode permitir que os usuários adicionem o restaurante como contato enquanto o avaliam. Para fazer isso usando uma intent, ela precisa ser criada usando o máximo de dados disponíveis e enviada ao app Contatos.

Inserir um contato usando o app Contatos insere um novo contato bruto nos Contatos Tabela ContactsContract.RawContacts do provedor. Se necessário, o app de contatos solicita aos usuários o tipo e a conta a serem usados ao criar o arquivo bruto contato O app de contatos também notifica os usuários se o contato bruto já existe. Os usuários têm a opção de cancelar a inserção, caso em que nenhum contato é criado. Para saber mais sobre contatos brutos, consulte a Provedor de contatos guia da API.

Criar uma intent

Para começar, crie um novo objeto Intent com a ação Intents.Insert.ACTION. Defina o tipo MIME como RawContacts.CONTENT_TYPE. Exemplo:

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 você já tem detalhes do contato, como um número de telefone ou endereço de e-mail, pode inseri-los na intent como dados estendidos. Para um valor de chave, use a constante apropriada de Intents.Insert. App Contatos exibe os dados na tela de inserção, permitindo que os usuários façam outras edições e inclusões.

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

Depois de criar a Intent, envie-a chamando startActivity().

Kotlin

    /* Sends the Intent
     */
    startActivity(intent)

Java

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

Essa chamada abre uma tela no app de contatos que permite que os usuários insiram um novo contato. O o tipo de conta e o nome da conta do contato estão listados na parte superior da tela. Depois que os usuários inserem os dados e clicam em Concluído, a lista de contatos do app de contatos aparece. Os usuários retornam ao seu app clicando em Voltar.

Editar um contato já existente usando uma intent

Editar um contato já existente usando uma Intent é útil se o usuário já tiver escolhido um contato de interesse. Por exemplo, um app que encontra contatos endereços postais, mas não têm um código postal pode dar aos usuários a opção de procurar o código e e adicioná-la ao contato.

Para editar um contato já existente usando uma intent, use um procedimento semelhante à inserção de um contato. Crie uma intent conforme descrito na seção Inserir um novo contato usando uma intent, mas adicionar o Contacts.CONTENT_LOOKUP_URI e o tipo MIME Contacts.CONTENT_ITEM_TYPE à intent. Para editar o contato com os detalhes que você já tem, insira-os nos dados estendidos da intent. Observe que algumas não podem ser editadas usando uma intent. essas colunas estão listadas no resumo da referência da API para a classe ContactsContract.Contacts sob o título "Atualizar".

Por fim, envie a intent. Como resposta, o app de contatos exibe uma tela de edição. Quando o usuário termina de editar e salva as edições, o app de contatos mostra uma lista de contatos. Quando o usuário clicar em Voltar, seu app será exibido.

Criar a intent

Para editar um contato, ligue para Intent(action) criar uma intent com a ação ACTION_EDIT. Chame setDataAndType() para definir o valor de dados da intent como o Contacts.CONTENT_LOOKUP_URI do contato e o tipo MIME como Contacts.CONTENT_ITEM_TYPE. Como uma chamada para setType() substitui o valor atual dos dados para Intent, você precisa definir os dados e o tipo MIME ao mesmo tempo.

Para receber o Contacts.CONTENT_LOOKUP_URI de um contato, chame Contacts.getLookupUri(id, lookupkey) com os valores Contacts._ID e Contacts.LOOKUP_KEY do contato como argumentos.

Observação: dados O valor de LOOKUP_KEY é o identificador que deve ser usado para recuperar um contato. Ela permanece constante, mesmo que o provedor altere o ID da linha do contato para lidar com operações internas.

O seguinte snippet mostra como criar um 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);

No Android 4.0 (API de nível 14) e versões mais recentes, um problema no app de contatos causa erros navegação. Quando o app envia uma intent de edição para o app Contatos, e os usuários editam e salvam uma contato, ao clicar em Voltar, ele vê a tela da lista de contatos. Para voltar a seu app, ele precisará clicar em Recentes e selecioná-lo.

Para contornar esse problema no Android 4.0.3 (API de nível 15) e versões mais recentes, adicione a chave de dados estendida finishActivityOnSaveCompleted à intent, com um valor true. As versões do Android anteriores ao Android 4.0 aceitam essa chave, mas ela não tem efeito. Para definir os dados estendidos, faça o seguinte:

Kotlin

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

Java

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

Adicionar outros dados estendidos

Para adicionar outros dados estendidos à Intent, chame putExtra(), conforme desejado. Você pode adicionar dados estendidos para campos de contato comuns usando os valores-chave especificados em Intents.Insert: Lembre-se de que algumas não é possível modificar as colunas na tabela ContactsContract.Contacts. Essas colunas estão listadas na seção de resumo da referência da API para a classe ContactsContract.Contacts no título "Atualizar".

Enviar a intent

Por fim, envie a intent que você construiu. Exemplo:

Kotlin

    // Sends the Intent
    startActivity(editIntent)

Java

    // Sends the Intent
    startActivity(editIntent);

Permitir que os usuários optem por inserir ou editar usando uma intent

Você pode permitir que os usuários escolham se querem inserir um contato ou editar um existente enviando um Intent com a ação ACTION_INSERT_OR_EDIT. Por exemplo, um app cliente de e-mail poderia permitir que os usuários adicionem um endereço de e-mail recebido a um novo contato ou como um endereço e o endereço de e-mail de um contato existente. Defina o tipo MIME dessa intent para Contacts.CONTENT_ITEM_TYPE, mas não o URI de dados.

Quando você enviar essa intent, o app Contatos exibirá uma lista de contatos. Os usuários podem inserir um novo contato ou escolher um já existente e editá-lo. Todos os campos de dados estendidos adicionados à intent preenchem a tela exibida. Você pode usar qualquer um dos valores de chave especificados em Intents.Insert. O seguinte snippet de código mostra como construir e enviar a 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);

Modificar contatos usando intents

Inserir um novo contato usando uma intent

Criar uma intent

Kotlin

Java

Kotlin

Java

Kotlin

Java

Editar um contato já existente usando uma intent

Criar a intent

Kotlin

Java

Adicionar a sinalização de navegação

Kotlin

Java

Adicionar outros dados estendidos

Enviar a intent

Kotlin

Java

Permitir que os usuários optem por inserir ou editar usando uma intent

Kotlin

Java