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
Referência: https://stackoverflow.com/questions/59137973/how-to-set-the-focus-to-an-inputtext-element