Tutorial de formulários acessíveis
O padrão que todo formulário Lily segue, seja qual for o framework: rotular cada controle, verificar ao enviar, colocar cada erro junto ao seu campo e resumir os erros onde o foco chega.
O que você vai construir
Um formulário de dois campos que, enviado com erros, diz o que está errado, junto a cada campo e num resumo no topo, e move o foco para lá, para que quem usa teclado ou leitor de tela encontre os erros de imediato. É mostrado em HTML simples com as classes do Lily; cada catálogo de framework gera a mesma marcação com os seus próprios componentes Field, Hint,
ErrorMessage e ErrorSummary . Cerca de 20 minutos; ajuda fazer antes o tutorial de HTML .
Passo 1 — Rotular cada controle e dizer o que se espera
<form class="form" novalidate>
<div class="field">
<label class="label" for="name">Full name</label>
<input class="text-input" type="text" id="name" name="name" autocomplete="name" required />
</div>
<div class="field">
<label class="label" for="email">Email</label>
<p class="hint" id="email-hint">We only use this to send your appointment.</p>
<input class="email-input" type="email" id="email" name="email"
autocomplete="email" aria-describedby="email-hint" required />
</div>
<button class="button" type="submit">Continue</button>
</form>
- Um
<label for>visível em cada controle, nunca um texto de exemplo no seu lugar: ele desaparece quando se digita. - Uma dica junta-se ao nome do campo por meio de
aria-describedby, de modo que um leitor de tela a lê junto com o campo. autocompletepermite que o navegador preencha o que já sabe (WCAG 1.3.5).-
novalidatedesliga os balões do próprio navegador, porque você mostrará os erros, com as suas palavras e no seu idioma. Os atributosrequiredetypecontinuam: o seu script lê-os.
Passo 2 — Verificar ao enviar, não enquanto se digita
Dizer a alguém que o e-mail está errado depois de uma letra é ruído. Verifique ao enviar. Os 63 temas já mostram um campo como inválido só depois de ele ser editado e deixado (:user-invalid), ou quando você define
aria-invalid="true", então nada fica vermelho ao carregar a página.
Nunca desative o botão de envio até o formulário ser válido: um botão desativado não consegue dizer porquê.
Passo 3 — Colocar cada erro junto ao seu campo
<div class="field">
<label class="label" for="email">Email</label>
<p class="hint" id="email-hint">We only use this to send your appointment.</p>
<p class="error-message" id="email-error">Enter an email address in the right format, like name@example.com</p>
<input class="email-input" type="email" id="email" name="email" autocomplete="email"
aria-invalid="true" aria-describedby="email-hint email-error" required />
</div>
aria-invalid="true"diz que o campo está errado; a mensagem diz porquê e como corrigir.- A mensagem está em
aria-describedby, depois da dica, por isso é lida quando o campo recebe o foco. - Diga o que fazer, não só o que está errado: «Introduza um endereço de e-mail no formato correto», e não «Inválido».
- Nunca só a cor: o texto é o erro; a borda vermelha apenas o repete (WCAG 1.4.1).
Passo 4 — Resumir os erros onde o foco chega
<div class="error-summary" role="alert" tabindex="-1" aria-labelledby="error-summary-title">
<h2 id="error-summary-title">There is a problem</h2>
<ul>
<li><a href="#name">Enter your full name</a></li>
<li><a href="#email">Enter an email address in the right format, like name@example.com</a></li>
</ul>
</div>
Coloque-o no topo do formulário e mova o foco para ele ao enviar. Cada ligação leva diretamente ao seu campo. tabindex="-1" permite que o resumo receba o foco sem acrescentar uma paragem de tabulação.
Passo 5 — O script que junta tudo
const messages = {
name: { valueMissing: "Enter your full name" },
email: {
valueMissing: "Enter your email address",
typeMismatch: "Enter an email address in the right format, like name@example.com",
},
};
const form = document.querySelector("form");
form.addEventListener("submit", (event) => {
form.querySelector(".error-summary")?.remove();
const errors = [];
for (const field of form.querySelectorAll("input")) {
const old = document.getElementById(field.id + "-error");
old?.remove();
const describedBy = (field.getAttribute("aria-describedby") ?? "")
.split(" ").filter((id) => id && id !== field.id + "-error");
const problem = Object.keys(messages[field.name] ?? {}).find((key) => field.validity[key]);
if (!problem) {
field.removeAttribute("aria-invalid");
field.setAttribute("aria-describedby", describedBy.join(" "));
continue;
}
const text = messages[field.name][problem];
const message = document.createElement("p");
message.className = "error-message";
message.id = field.id + "-error";
message.textContent = text;
field.before(message);
field.setAttribute("aria-invalid", "true");
field.setAttribute("aria-describedby", [...describedBy, message.id].join(" "));
errors.push({ id: field.id, text });
}
if (errors.length === 0) return; // valid: let it submit
event.preventDefault();
const summary = document.createElement("div");
summary.className = "error-summary";
summary.setAttribute("role", "alert");
summary.tabIndex = -1;
summary.setAttribute("aria-labelledby", "error-summary-title");
summary.innerHTML = '<h2 id="error-summary-title">There is a problem</h2><ul></ul>';
for (const { id, text } of errors) {
const link = document.createElement("a");
link.href = "#" + id;
link.textContent = text;
const item = document.createElement("li");
item.append(link);
summary.querySelector("ul").append(item);
}
form.prepend(summary);
summary.focus();
});
As mensagens são suas, no seu idioma: a propriedade
validity do navegador diz que regra falhou, e a sua tabela diz o que comunicar à pessoa. O Lily não traz texto em inglês para traduzir.
Verifique o seu trabalho: envie o formulário vazio pelo teclado. O foco passa para o resumo e um leitor de tela lê «There is a problem» e os dois erros. Siga uma ligação: o foco chega ao campo, lido com a sua dica e o seu erro. Corrija os dois e envie: o formulário segue, sem erros pendentes.
O que evitar
- Limitar ou corrigir o que alguém digitou sem dizer; diga-lhe.
- Limpar um formulário quando há erro: guarde tudo o que foi introduzido.
- Um erro que só aparece ao passar o ponteiro, ou só numa dica flutuante.
- Expirar um formulário sem aviso; use
timeout-dialogpara avisar e prolongar.
Próximos passos
- Formação — oito módulos, cada um com um exercício e uma autoavaliação.
- ErrorSummary, Field e ErrorMessage no catálogo.
- Um formulário que funciona em todo o mundo — nomes, moradas, datas e direção da escrita.
- Temas — o estado inválido que cada tema desenha.