Programação Por Equipe DevBras

Capa do artigo: Foco no campo com erro em formulário Blazor

Foco no campo com erro em formulário Blazor

Leve o foco ao primeiro campo inválido após o envio, ao primeiro campo ao abrir e ligue o erro com aria-describedby. Com verificador do HTML do Blazor.

Num formulário Blazor, o foco deve ir para o primeiro campo inválido logo depois de um envio que falhou na validação, e para o primeiro campo ao abrir uma tela cuja tarefa principal é preencher aquele formulário. Fora desses momentos (e de abrir ou fechar um diálogo), o código não deve mover o foco sem a pessoa pedir. A mensagem de erro em vermelho no meio da página não basta: quem usa teclado precisa achar o campo, e quem usa leitor de tela só ouve o que está em foco.

Abaixo estão o código do EditForm com FocusAsync e OnInvalidSubmit, o motivo de o foco no erro precisar esperar o render seguinte, e um verificador em Python que lê o HTML renderizado e aponta mensagem de erro que o leitor de tela não vai anunciar; ele achou um aria-describedby quebrado no HTML de teste, com a saída real mais abaixo.

O que o foco decide

O foco é o lugar onde a próxima tecla cai. Quem usa mouse compensa um foco mal posicionado clicando no campo certo. Quem usa teclado aperta Tab várias vezes até achar o campo errado, sem saber qual é. Quem usa leitor de tela ouve o elemento em foco; se o foco ficou no botão, ouve "Salvar, botão" e nada sobre o erro.

O critério de sucesso 3.3.1 das WCAG, identificação de erro, pede que o campo com erro seja identificado e o erro descrito em texto. O tutorial de formulários do W3C, na parte de notificações, sugere o passo seguinte: quando o envio tem erros, levar o foco ao primeiro campo com erro. E para que o leitor anuncie a mensagem junto com o campo, ela precisa estar ligada a ele, com aria-describedby apontando para o id do elemento que contém o texto.

Quando mexer no foco

Mova: ao abrir uma página que é só o formulário (login, cadastro); depois de um envio que falhou na validação; ao abrir um diálogo; ao fechar o diálogo, de volta a quem o abriu, como em modal que devolve o foco.

Não mova: enquanto a pessoa digita, porque uma busca em segundo plano terminou; ao carregar uma página com conteúdo para ler acima do formulário; quando uma validação "ao sair do campo" acusa erro e a pessoa já está no campo seguinte. Para avisos que não pedem ação ("salvo às 14:32"), use uma região com aria-live="polite", que o leitor anuncia sem tirar o foco do lugar.

O formulário em Blazor

@inject IJSRuntime JS

<EditForm Model="cliente" OnValidSubmit="Salvar" OnInvalidSubmit="AoFalhar" id="form-cliente">
    <DataAnnotationsValidator />

    <label for="nome">Nome completo</label>
    <InputText id="nome" @ref="campoNome" @bind-Value="cliente.Nome"
               aria-describedby="erro-nome" />
    <div id="erro-nome"><ValidationMessage For="() => cliente.Nome" /></div>

    <label for="cpf">CPF</label>
    <InputText id="cpf" @bind-Value="cliente.Cpf" inputmode="numeric"
               aria-describedby="erro-cpf" />
    <div id="erro-cpf"><ValidationMessage For="() => cliente.Cpf" /></div>

    <button type="submit">Salvar</button>
</EditForm>

@code {
    Cliente cliente = new();
    InputText? campoNome;
    bool focarErro;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender && campoNome?.Element is ElementReference el)
        {
            await el.FocusAsync();
            return;
        }
        if (focarErro)
        {
            focarErro = false;
            await JS.InvokeVoidAsync("focarPrimeiroInvalido", "#form-cliente");
        }
    }

    void AoFalhar(EditContext contexto) => focarErro = true;
    async Task Salvar() { /* grava e navega */ }
}
// wwwroot/js/foco.js, incluído na página principal
window.focarPrimeiroInvalido = function (seletorDoForm) {
    const campo = document.querySelector(seletorDoForm + " .invalid");
    if (campo) campo.focus();
};

O foco inicial não precisa de JavaScript seu: os componentes de input expõem o elemento HTML pela propriedade Element, e o método de extensão FocusAsync aplica o foco a partir do C#.

Por que o foco no erro espera o render seguinte

Quando o AoFalhar roda, o Blazor ainda não atualizou o HTML com o estado de erro. A documentação de validação de formulários lista as classes que ele aplica: valid ou invalid nos inputs, mais modified depois que a pessoa edita, e validation-message nas mensagens. Essas classes só existem no DOM depois do render, e o OnAfterRenderAsync é o primeiro momento em que o seletor .invalid encontra alguma coisa. Por isso o AoFalhar só marca a intenção, e o foco acontece no ciclo seguinte.

A mesma documentação lembra que entradas com validação assíncrona usam pending ou faulted enquanto o estado se aplica. Se o seu formulário tem esse tipo de campo, confira no HTML gerado pela sua versão quais classes aparecem antes de confiar no seletor.

Conferindo o HTML renderizado

O erro mais comum nesse padrão não aparece na tela: um aria-describedby que aponta para um id que não existe, por erro de digitação ou porque alguém renomeou a div. A mensagem aparece em vermelho e o leitor de tela fica mudo sobre ela. Este verificador lê o HTML do formulário (copiado do DevTools depois de um envio com erro), lista os campos inválidos e diz o que seria anunciado em cada um:

#!/usr/bin/env python3
import sys
from html.parser import HTMLParser

class Form(HTMLParser):
    def __init__(s):
        super().__init__(); s.inputs=[]; s.labels={}; s.textos={}; s.pilha=[]; s.label_for=None
    def handle_starttag(s, tag, a):
        a = dict(a)
        if tag == "input": s.inputs.append(a)
        if tag == "label": s.label_for = a.get("for")
        s.pilha.append(a.get("id"))
    def handle_endtag(s, tag):
        if tag == "label": s.label_for = None
        if s.pilha: s.pilha.pop()
    def handle_data(s, d):
        d = d.strip()
        if not d: return
        if s.label_for: s.labels[s.label_for] = d
        for i in s.pilha:
            if i: s.textos[i] = (s.textos.get(i, "") + " " + d).strip()

f = Form(); f.feed(open(sys.argv[1]).read())
invalidos = [i for i in f.inputs if "invalid" in i.get("class", "").split()]
print(f"campos inválidos: {[i['id'] for i in invalidos]}")
for i in invalidos:
    ref = i.get("aria-describedby")
    msg = f.textos.get(ref)
    if msg is None:
        print(f"  {i['id']}: aria-describedby='{ref}' não existe na página -> erro não é anunciado")
    else:
        print(f"  {i['id']}: leitor anuncia \"{f.labels.get(i['id'])}, editar texto, {msg}\"")
if invalidos: print(f"foco vai para: #{invalidos[0]['id']} (primeiro na ordem do formulário)")

Rodamos num HTML de teste no formato que o Blazor gera, com três campos e um erro proposital no terceiro (erro-mail no input, erro-email na div):

$ python3 confere-foco.py form-renderizado.html
campos inválidos: ['cpf', 'email']
  cpf: leitor anuncia "CPF, editar texto, O campo CPF é obrigatório."
  email: aria-describedby='erro-mail' não existe na página -> erro não é anunciado
foco vai para: #cpf (primeiro na ordem do formulário)

A frase "leitor anuncia" é uma aproximação do que NVDA, JAWS ou VoiceOver dizem; a ordem e as palavras exatas variam entre leitores. O que o script garante é que a ligação existe. No caso do CPF, a atendente envia com o campo em branco, o cursor vai para ele e o leitor junta rótulo e erro numa frase só. Ela corrige e envia de novo sem procurar nada.

Sem Blazor, a mesma ideia

Em HTML com JavaScript, o padrão é igual: no submit, valide; se houver erro, cancele o envio, marque os campos com aria-invalid="true" e foque o primeiro. O atributo autofocus resolve o foco inicial em páginas que são só formulário, sem script. O anel de foco precisa continuar visível em qualquer tema, como mostra foco visível no escuro.

Equipe DevBras

Avalie este artigo

Referência: https://stackoverflow.com/questions/59137973/how-to-set-the-focus-to-an-inputtext-element