Preenchimento automático no Compose

Beta: este documento é para a versão Beta das APIs de preenchimento automático. Envie feedback pelo nosso Issue Tracker.

Alguns apps, como gerenciadores de senhas, podem preencher os componentes em outros apps com dados fornecidos pelo usuário. Os apps que preenchem componentes de outros apps são chamados de serviços de preenchimento automático. A estrutura de preenchimento automático gerencia a comunicação entre um app e um serviço de preenchimento automático.

Preencher credenciais e formulários é uma tarefa demorada e propensa a erros. O preenchimento automático permite que os usuários economizem tempo preenchendo campos e minimiza os erros de entrada do usuário.

Com apenas algumas linhas de código, você pode implementar o preenchimento automático no Compose. Esse recurso oferece os seguintes benefícios aos usuários:

Preencher credenciais

O preenchimento automático permite que os usuários preencham as credenciais das seguintes maneiras:

• O sistema mostra sugestões de preenchimento automático para o usuário quando ele toca em um campo em que a semântica de preenchimento automático está definida.
• O sistema mostra sugestões de preenchimento automático para o usuário e as filtra com base no que o usuário digita.

Salvar credenciais

Os usuários podem salvar credenciais com o preenchimento automático das seguintes maneiras:

• O sistema aciona uma caixa de diálogo de salvamento, que solicita que o usuário salve as informações quando ele inserir informações novas ou atualizadas em um campo ativado para preenchimento automático. A economia pode ser feita de duas maneiras:
  • Explicitamente, ao confirmar informações (por exemplo, com um clique no botão)
  • Implicitamente, quando um usuário sai da página
• Dependendo do provedor de credenciais, o sistema pode sugerir uma senha forte para o usuário quando um campo tiver ContentType.NewPassword definido.

Você pode usar o preenchimento automático no seu app para agilizar a recuperação de dados salvos para os usuários. O preenchimento automático oferece suporte a componentes de texto por meio de BasicTextField e todos os campos de texto do Material Design que são criados com base nesse componente.

Conf. preench. aut.

Antes de usar as APIs de preenchimento automático no dispositivo ou emulador, é necessário ativar o preenchimento automático nas Configurações. Nele, você pode especificar um provedor de credenciais para que o preenchimento automático armazene suas credenciais.

Figura 1. Uma página de configurações mostrando como especificar um provedor de credenciais.

Adicionar preenchimento automático ao campo de texto usando o tipo de conteúdo

Para indicar que um TextField está ativado para preenchimento automático, defina a semântica ContentType com os tipos que o campo pode aceitar. Isso indica aos serviços de preenchimento automático que tipo de dados do usuário pode ser relevante para esse campo específico. Use ContentType.Username para definir um TextField que os usuários podem preencher com o nome de usuário.

TextField(
    value = textFieldValue.value,
    onValueChange = {textFieldValue.value = it},
    modifier = Modifier.semantics { contentType = ContentType.Username }
)
AutofillSnippets.kt

Ao definir a semântica ContentType, os usuários podem acessar as informações de preenchimento automático já salvas no provedor de credenciais do dispositivo. Por exemplo, se um usuário já tiver feito login no seu app pelo navegador Chrome no laptop e salvo a senha em um provedor de credenciais, as credenciais serão exibidas para ele pelo preenchimento automático.

Adicionar campos de preenchimento automático com vários tipos

Em alguns casos, talvez você queira que o TextField assuma mais de um ContentType. Por exemplo, um campo de login pode aceitar um endereço de e-mail ou um nome de usuário. É possível adicionar vários tipos de conteúdo ao TextField com o operador +.

TextField(
    value = textFieldValue.value,
    onValueChange = { textFieldValue.value = it },
    modifier = Modifier.semantics {
        contentType = ContentType.Username + ContentType.EmailAddress
    }
)
AutofillSnippets.kt

Para saber quais tipos de dados podem ser salvos com o Preenchimento automático, consulte a referência ContentType.

Preencher dados com o Preenchimento automático

Quando você adiciona um ContentType em um TextField, não é necessário fazer mais nada para que os usuários possam preencher as credenciais.

Quando um usuário clica em um campo ativado para preenchimento automático, se houver dados relevantes armazenados, ele vai ver um ícone na barra de ferramentas acima do teclado que solicita o preenchimento das credenciais.

Figura 2. Chips na barra de ferramentas de texto mostrando as credenciais salvas.

Salvar dados com o preenchimento automático durante a navegação

O Compose tenta determinar automaticamente quando um usuário navega de uma página e confirma as credenciais inseridas. Depois que um campo é ativado para o preenchimento automático, ele salva automaticamente as informações de credencial quando um usuário sai da página sem precisar de nenhum código extra.

Salvar dados explicitamente com o preenchimento automático

Para salvar explicitamente novas credenciais em campos de texto com o Preenchimento automático, o contexto do Preenchimento automático precisa ser confirmado (ou cancelado) pelo gerenciador. O gerenciador de preenchimento automático local se comunica com o framework de preenchimento automático sempre que necessário. Se você quiser remover as credenciais que o usuário inseriu, chame AutofillManager.cancel para excluir todos os dados pendentes sem salvá-los.

Os snippets a seguir mostram como salvar dados com o preenchimento automático usando explicitamente um botão:

1. Crie uma variável local para armazenar o gerenciador de preenchimento automático, que pode ser recuperado da seguinte maneira:

   val autofillManager = LocalAutofillManager.current
   AutofillSnippets.kt

2. Em TextField(s), adicione o tipo de conteúdo desejado usando Modifier.semantics:

   val autofillManager = LocalAutofillManager.current
   
   Column {
       TextField(
           value = textFieldValue.value,
           onValueChange = { textFieldValue.value = it },
           modifier = Modifier.semantics { contentType = ContentType.NewUsername }
       )
   
       Spacer(modifier = Modifier.height(16.dp))
   
       TextField(
           value = textFieldValue.value,
           onValueChange = { textFieldValue.value = it },
           modifier = Modifier.semantics { contentType = ContentType.NewPassword }
       )
   }
   AutofillSnippets.kt

3. Confirme o contexto de preenchimento automático conforme necessário com um clique no botão:

   val autofillManager = LocalAutofillManager.current
   
   Column {
       TextField(
           value = textFieldValue.value,
           onValueChange = { textFieldValue.value = it },
           modifier = Modifier.semantics { contentType = ContentType.NewUsername },
       )
   
       Spacer(modifier = Modifier.height(16.dp))
   
       TextField(
           value = textFieldValue.value,
           onValueChange = { textFieldValue.value = it },
           modifier = Modifier.semantics { contentType = ContentType.NewPassword },
       )
   
       // Submit button
       Button(onClick = { autofillManager?.commit() }) { Text("Reset credentials") }
   }
   AutofillSnippets.kt

Commit é chamado sempre que um usuário sai da tela. Se um botão Enviar estiver vinculado à navegação, não será necessário chamar Commit. Se você ainda quiser clicar em Enviar para acionar a caixa de diálogo de salvamento, adicione Confirmar aqui.

Quando o usuário clicar no botão, a página inferior vai aparecer, solicitando que ele salve as credenciais no provedor selecionado:

Figura 3. Página inferior solicitando que os usuários salvem a senha.

Salvar dados com o preenchimento automático sugerindo uma senha forte

Dependendo do provedor de credenciais, quando você usa os tipos de conteúdo NewUsername e NewPassword, os usuários podem ver um botão no teclado para Sugerir senha forte. Quando clicam nele, uma página inferior aparece, permitindo que salvem as credenciais. Não é necessário implementar nada mais para que os usuários tenham essa experiência.

Figura 4. O ícone de senha forte sugerida na barra de ferramentas do teclado.

Figura 5. Página inferior solicitando que os usuários usem uma senha forte.

Solução de problemas

Ao invocar a jornada de usuário "salvando", se você clicar em "Não agora" mais de uma vez, o provedor de credenciais pode não mostrar mais a página inferior. Para reativá-la e fazer com que ela apareça novamente, é necessário remover apps específicos que bloquearam a opção "Lembrar essa senha?".

Figura 6.Página inferior solicitando que os usuários salvem a senha.

Personalizar ainda mais o preenchimento automático

Em uma jornada de usuário típica de preenchimento automático, quando um componente ativado por preenchimento automático é preenchido com credenciais, ele muda de cor e fica destacado para indicar ao usuário que o preenchimento automático foi concluído.

Para personalizar essa cor de destaque, use CompositionLocal e informe a cor que você quiser.

val customHighlightColor = Color.Red

CompositionLocalProvider(LocalAutofillHighlightColor provides customHighlightColor) {
    TextField(
        value = textFieldValue.value,
        onValueChange = { textFieldValue.value = it },
        modifier = Modifier.semantics { contentType = ContentType.Username }
    )
}
AutofillSnippets.kt

A cor de destaque padrão do preenchimento automático é definida como Color(0x4dffeb3b).