Skip to main content
Validação HTML

O atributo "aria-describedby" deve apontar para um elemento no mesmo documento.

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 de aria-describedby não corresponde exatamente ao id do 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 id de um elemento foi alterado ou o elemento foi removido, mas a referência aria-describedby nã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

  1. Verifique erros ortográficos. Compare o valor em aria-describedby com o id do elemento alvo. Lembre-se de que a correspondência de id é sensível a maiúsculas e minúsculas — helpText e helptext são diferentes.
  2. Adicione o elemento em falta. Se o elemento descritivo ainda não existe, crie-o com o id correspondente.
  3. Remova referências obsoletas. Se a descrição já não é necessária, remova completamente o atributo aria-describedby em vez de deixar uma referência quebrada.
  4. Verifique todos os IDs numa lista de múltiplos valores. Se aria-describedby conté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.

Ajude-nos a melhorar os nossos guias

Este guia foi útil?

Pronto para validar os seus sites?
Comece o seu teste gratuito hoje.