Error State — o que é, exibição de erros de campo e implementação no Android

O que é estado de erro de campo no Android?

Error State é um modo de exibição especial de um campo de entrada que é ativado quando os dados inseridos falham na validação. Visualmente, o Error State inclui três componentes: uma mudança na cor da borda ou fundo do campo (geralmente para vermelho), o aparecimento de uma mensagem de texto abaixo do campo descrevendo o erro e, opcionalmente, um ícone ou destaque. O objetivo do Error State é atrair instantaneamente a atenção do usuário para o campo problemático e sugerir como corrigir o erro.

No Android, o Error State é implementado no nível do TextInputLayout do Material Design Components. O TextInputLayout envolve o EditText e gerencia seus estados: normal, focused, error, disabled. O método setError(String) alterna o campo para o estado de erro, altera a cor da borda e exibe a mensagem. Quando o texto muda ou setError(null) é chamado, o campo retorna ao normal.

De acordo com as Material Design Guidelines, o Error State deve ser perceptível, mas não dominante. A cor vermelha da borda deve contrastar com o estado normal, mas não sobrecarregar a interface. A mensagem de erro deve conter informações específicas sobre o problema e como resolvê-lo. Um ícone de erro (por exemplo, um círculo vermelho com um ponto de exclamação) reforça o sinal visual.

Como o setError funciona no TextInputLayout

O método setError(CharSequence errorText) alterna o TextInputLayout para o estado de erro. O parâmetro errorText é o texto exibido abaixo do campo. Se null for passado, o erro é limpo. O TextInputLayout gerencia a animação: o texto de erro aparece com um fade-in suave, a borda muda para vermelho. Um ícone de erro (padrão: ponto de exclamação em um círculo) é mostrado no final do campo.

Detalhes importantes: setErrorEnabled(true) deve ser chamado antes de setError para reservar espaço para a mensagem de erro. Caso contrário, o layout pode "pular" quando o erro aparecer porque o espaço não está reservado. Recomenda-se sempre ativar o suporte a erro no XML através de app:errorEnabled="true" para evitar deslocamentos do layout.

O método setError é limpo automaticamente quando o texto do campo muda se setErrorEnabled(true) estiver ativado. Esse comportamento é conveniente para validação em tempo real: assim que o usuário começa a corrigir o erro, a borda vermelha desaparece e o campo retorna ao normal. No entanto, para cenários complexos, essa limpeza automática pode ser indesejável — nesses casos, gerencie o erro manualmente.

val til = findViewById<TextInputLayout>(R.id.til_email)

// Ativar suporte a erro (definir em XML caso contrário)
til.isErrorEnabled = true

// Definir mensagem de erro
til.error = "Invalid email address"

// Limpar erro
til.error = null

// Verificar se o erro existe
if (til.error != null) {
    // O campo está em estado de erro
}

O exemplo usa propriedades do Kotlin para acessar setError/isErrorEnabled. O TextInputLayout atualiza automaticamente a interface: altera o boxStrokeColor, mostra o ícone de erro, exibe o texto de erro. Se o texto no EditText mudar, o erro é limpo automaticamente. Para redefinição manual, defina error = null.

Formas alternativas de exibir erros

Nem todos os projetos usam Material Design Components. Para exibição personalizada de erros, você pode usar um TextView separado abaixo do EditText que se torna visível ao ocorrer um erro. Essa abordagem oferece controle total sobre estilos e posicionamento da mensagem. Por exemplo, você pode colocar a mensagem à direita do campo, usar uma cor de fundo diferente ou adicionar um ícone à esquerda do texto.

No Jetpack Compose, o Error State é implementado através do parâmetro isError no OutlinedTextField ou TextField. Quando isError = true, a borda fica vermelha e você pode mostrar o texto de erro através do supportingText. O Compose não possui limpeza automática interna ao alterar o texto — o desenvolvedor gerencia o estado de erro manualmente usando remember e mutableStateOf.

Para erros de grupo (uma única mensagem para vários campos, por exemplo, "Preencha todos os campos obrigatórios"), use Snackbar, Dialog ou um bloco inline no topo do formulário. Um erro de grupo não substitui o Error State de campos individuais, mas o complementa. O usuário primeiro vê a mensagem geral e depois procura campos específicos com erros.

Cores, ícones e animação de erros

A cor do Error State no Material Design Components é controlada através do atributo boxStrokeErrorColor ou do atributo colorError no tema. Por padrão, a cor vermelha do sistema é usada, mas pode ser substituída no tema do aplicativo ou diretamente no TextInputLayout através de app:boxStrokeErrorColor="@color/customErrorColor". Para suporte a tema escuro, recomenda-se usar um seletor com cores diferentes para os modos claro e escuro.

Ícone de erro é configurado através de app:errorIconDrawable. Por padrão, um ponto de exclamação em um círculo é exibido. Pode ser substituído por um ícone personalizado ou removido completamente definindo app:errorIconDrawable="@null". O ícone é exibido no final do TextInputLayout e serve como um marcador visual adicional. No Material Design 3, o ícone de erro é obrigatório para acessibilidade.

Animação de aparecimento do erro é integrada ao TextInputLayout: o texto desliza de baixo para cima com uma mudança suave de opacidade. Para animação personalizada, use a Transition API ou MotionLayout. Por exemplo, agitar o campo ao ocorrer um erro atrai atenção adicional. No entanto, o uso excessivo de animação prejudica a UX — o aparecimento suave da mensagem é suficiente.

Gerenciamento do estado de erro durante a validação

O gerenciamento do Error State é dividido em duas etapas: definir o erro durante a validação do campo e limpar o erro ao corrigir. No caso mais simples, a validação é chamada em TextWatcher.afterTextChanged: se o valor for inválido, setError é chamado com uma mensagem de erro. Se for válido, setError(null) é chamado. O TextInputLayout oculta automaticamente o erro quando setError(null) limpa o estado.

Para validação de formulário, os erros são definidos na etapa de envio do formulário. Percorra todos os campos, valide cada um, defina erros para campos inválidos e foque no primeiro campo com erro. O botão de envio é bloqueado durante esse processo. Se o formulário for grande, recomenda-se rolar para o primeiro campo com erro e definir o foco automaticamente.

A regra de foco único de erro: ao enviar um formulário, defina o foco apenas no primeiro campo com erro. O usuário corrige um erro de cada vez e, após a correção, o próximo campo com erro recebe o foco automaticamente. Essa abordagem passo a passo reduz a carga cognitiva. O Material TextInputLayout não intercepta o foco ao definir um erro — isso deve ser feito manualmente através de requestFocus().

Erros comuns ao trabalhar com Error State

O primeiro erro — falta de isErrorEnabled. Se setErrorEnabled não for chamado antes de setError, o layout pode se deslocar quando a mensagem de erro aparecer. Isso é especialmente crítico se o campo estiver no meio da tela — o usuário perde a posição de rolagem. Sempre ative setErrorEnabled(true) no XML através de app:errorEnabled="true" ou programaticamente antes de definir um erro.

O segundo erro — mensagem de erro muito longa. O texto longo é dividido em várias linhas e pode sobrepor campos vizinhos. O comprimento recomendado da mensagem de erro é de 20 a 40 caracteres. Se mais informações forem necessárias, use helperText no estado normal ou uma dica de ferramenta para explicação adicional. A brevidade é a base de um bom Error State.

O terceiro erro — ignorar a acessibilidade. O Error State deve ser acessível para leitores de tela. O TextInputLayout anuncia automaticamente o erro através de contentDescription, mas implementações personalizadas devem fazer isso manualmente. Use announceForAccessibility() ou android:importantForAccessibility para mensagens de erro. Os usuários do TalkBack devem ouvir o erro imediatamente após seu aparecimento.