Nós ARIA treeitem devem ter um nome acessível

O papel treeitem representa um item dentro de um widget hierárquico tree, comummente usado para exploradores de ficheiros, menus de navegação aninhados, ou listas de categorias expansíveis. Quando um treeitem carece de um nome acessível, os leitores de ecrã anunciam algo como “item da árvore” sem mais contexto, tornando impossível para utilizadores que dependem de tecnologia assistiva distinguir um item de outro ou compreender a estrutura da árvore.

Este problema afeta principalmente utilizadores de leitores de ecrã, mas também pode impactar utilizadores de software de controlo por voz que precisam de referenciar elementos pelo nome para interagir com eles.

Esta regra relaciona-se com o Critério de Sucesso 4.1.2 das WCAG 2.1 (Name, Role, Value), que exige que todos os componentes de interface de utilizador tenham um nome que possa ser determinado programaticamente. Também suporta o Critério de Sucesso 1.3.1 (Info and Relationships), garantindo que informação transmitida através da estrutura está disponível para todos os utilizadores.

Como corrigir

Pode dar um nome acessível a um treeitem de várias formas:

1. Conteúdo de texto interno — Coloque texto descritivo diretamente dentro do elemento.
2. aria-label — Adicione um atributo aria-label com uma string descritiva.
3. aria-labelledby — Referencie o id de outro elemento que contenha o texto da etiqueta.
4. Atributo title — Use o atributo title como último recurso (menos fiável entre tecnologias assistivas).

O nome acessível deve ser conciso e descrever claramente o propósito ou conteúdo do item.

Exemplos

Incorreto: treeitem sem nome acessível

<ul role="tree">
  <li role="treeitem"></li>
  <li role="treeitem"></li>
</ul>

Os leitores de ecrã anunciam estes itens como “item da árvore” sem nenhuma etiqueta distintiva.

Incorreto: treeitem com apenas um elemento filho não textual e sem etiqueta

<ul role="tree">
  <li role="treeitem">
    <span class="icon-folder"></span>
  </li>
</ul>

Se o span renderiza apenas um ícone CSS e não contém texto, o treeitem ainda não tem um nome acessível.

Correto: treeitem com conteúdo de texto visível

<ul role="tree">
  <li role="treeitem">Documentos</li>
  <li role="treeitem">Fotografias</li>
  <li role="treeitem">Música</li>
</ul>

Correto: treeitem com aria-label

<ul role="tree">
  <li role="treeitem" aria-label="Documentos">
    <span class="icon-folder"></span>
  </li>
  <li role="treeitem" aria-label="Fotografias">
    <span class="icon-folder"></span>
  </li>
</ul>

Correto: treeitem com aria-labelledby

<ul role="tree">
  <li role="treeitem" aria-labelledby="item1-label">
    <span class="icon-folder"></span>
    <span id="item1-label">Documentos</span>
  </li>
  <li role="treeitem" aria-labelledby="item2-label">
    <span class="icon-folder"></span>
    <span id="item2-label">Fotografias</span>
  </li>
</ul>

Correto: elementos treeitem aninhados com nomes acessíveis

<ul role="tree">
  <li role="treeitem" aria-expanded="true">
    Documentos
    <ul role="group">
      <li role="treeitem">Currículo.pdf</li>
      <li role="treeitem">Carta de Apresentação.docx</li>
    </ul>
  </li>
  <li role="treeitem" aria-expanded="false">
    Fotografias
  </li>
</ul>

Cada treeitem na árvore — incluindo os aninhados — deve ter um nome acessível. Ao construir widgets de árvore, certifique-se também da interação adequada pelo teclado (teclas de seta para navegação, Enter/Espaço para ativação) e uso correto de aria-expanded em itens pai que contenham grupos filhos.

Learn more:

Deque Reference

Deque University - How To Fix

→