Sobre este problema HTML
O atributo aria-describedby é uma parte fundamental do WAI-ARIA, a especificação da Web Accessibility Initiative para tornar o conteúdo web mais acessível. Funciona criando uma relação entre um elemento e um ou mais outros elementos que fornecem texto descritivo adicional. Leitores de ecrã e outras tecnologias assistivas usam esta relação para anunciar o texto descritivo quando um utilizador interage com o elemento.
Quando define aria-describedby="some-id", o navegador procura um elemento com id="some-id" no mesmo documento. Se não existir nenhum elemento correspondente, a referência fica quebrada. Isto significa que as tecnologias assistivas não conseguem encontrar a descrição, e o atributo não faz nada silenciosamente. O validador W3C sinaliza isto como um erro porque uma referência pendente indica um bug — ou o elemento referenciado foi removido, renomeado, ou nunca foi adicionado.
Este problema surge frequentemente devido a:
-
Erros ortográficos no valor do
id— o valor dearia-describedbynão corresponde exatamente aoiddo elemento alvo (a correspondência é sensível a maiúsculas e minúsculas). - Conteúdo dinâmico — o elemento descrito é renderizado condicionalmente ou injetado por JavaScript após a validação.
- Erros de copiar-colar — o markup foi copiado de outra página ou componente, mas o elemento referenciado não foi incluído.
-
Refatorização — o
idde um elemento foi alterado ou o elemento foi removido, mas a referênciaaria-describedbynão foi atualizada.
Múltiplos valores de id podem ser listados em aria-describedby, separados por espaços. Cada id nessa lista deve resolver para um elemento no documento. Se mesmo um estiver em falta, o validador reportará um erro para essa referência.
Como corrigir
-
Verifique erros ortográficos. Compare o valor em
aria-describedbycom oiddo elemento alvo. Lembre-se de que a correspondência deidé sensível a maiúsculas e minúsculas —helpTextehelptextsão diferentes. -
Adicione o elemento em falta. Se o elemento descritivo ainda não existe, crie-o com o
idcorrespondente. -
Remova referências obsoletas. Se a descrição já não é necessária, remova completamente o atributo
aria-describedbyem vez de deixar uma referência quebrada. -
Verifique todos os IDs numa lista de múltiplos valores. Se
aria-describedbycontém múltiplos IDs separados por espaços, confirme que cada um existe.
Exemplos
Referência quebrada (desencadeia o erro)
Neste exemplo, aria-describedby aponta para password-help, mas não existe nenhum elemento com esse id no documento:
<label for="password">Password</label>
<input type="password" id="password" aria-describedby="password-help">
Corrigido adicionando o elemento referenciado
Adicionar um elemento com id="password-help" resolve o problema:
<label for="password">Password</label>
<input type="password" id="password" aria-describedby="password-help">
<p id="password-help">Must be at least 8 characters with one number.</p>
Referência quebrada devido a erro ortográfico
Aqui o valor de aria-describedby usa maiúsculas e minúsculas diferentes do id do elemento:
<input type="text" id="email" aria-describedby="emailHelp">
<small id="emailhelp">We'll never share your email.</small>
A correção é fazer os valores de id corresponderem exatamente:
<input type="text" id="email" aria-describedby="email-help">
<small id="email-help">We'll never share your email.</small>
Múltiplos IDs com um em falta
Ao listar múltiplas descrições, cada id deve estar presente:
<!-- "format-hint" existe mas "length-hint" não — isto desencadeia o erro -->
<input type="text" id="username" aria-describedby="format-hint length-hint">
<span id="format-hint">Letters and numbers only.</span>
Corrija-o adicionando o elemento em falta:
<input type="text" id="username" aria-describedby="format-hint length-hint">
<span id="format-hint">Letters and numbers only.</span>
<span id="length-hint">Between 3 and 20 characters.</span>
Remover o atributo quando nenhuma descrição é necessária
Se o conteúdo descritivo foi removido e já não é relevante, simplesmente remova o atributo aria-describedby:
<input type="text" id="search">
Encontre problemas como este automaticamente
O Rocket Validator analisa milhares de páginas em segundos, detetando problemas HTML em todo o seu site.