12k
All articles

O que é a árvore de acessibilidade?

Entenda como os navegadores criam a árvore de acessibilidade, calculam funções e nomes, inspecionam no DevTools e testam controles com Playwright.

OpenReplay Team
OpenReplay Team
O que é a árvore de acessibilidade?

A árvore de acessibilidade é uma segunda representação de uma página web que o navegador constrói a partir do DOM para as tecnologias assistivas. Ela mantém o papel (role), o nome acessível, o estado e o valor de cada elemento relevante e descarta a maioria dos wrappers que existem apenas para layout.

Você se depara com ela quando uma auditoria aponta “button has no accessible name”, quando um linter reclama de uma div clicável ou quando o getByRole do Playwright não encontra um elemento que está visível na tela. Os três casos dizem respeito à mesma estrutura. Este artigo explica como o navegador constrói essa árvore, o que cada nó contém, como inspecioná-la e como escrever testes com base nela.

Principais pontos

  • Os navegadores constroem a árvore de acessibilidade a partir do DOM, da semântica nativa do HTML e dos atributos ARIA. Elementos div e span usados apenas para estilização geralmente não ganham um nó próprio.
  • Conteúdo oculto com display: none, visibility: hidden, o atributo hidden ou aria-hidden="true" fica fora da árvore de acessibilidade, embora continue no DOM.
  • De forma simplificada, o nome acessível de um elemento vem primeiro de aria-labelledby, depois de aria-label, em seguida da rotulagem nativa (<label>, alt), depois do conteúdo textual e, por fim, de title.
  • Uma <div> com um manipulador de clique não tem o papel de botão na árvore. Por isso, os leitores de tela não a anunciam como um controle e os usuários de teclado não conseguem alcançá-la.
  • O locator getByRole e os ARIA snapshots do Playwright funcionam com base em papéis e nomes acessíveis. Assim, testes escritos com eles falham pelos mesmos bugs que bloqueiam usuários de tecnologias assistivas.

Como o navegador constrói a árvore de acessibilidade

Os navegadores constroem a árvore de acessibilidade a partir de três fontes: o DOM, a semântica nativa dos elementos HTML e os atributos ARIA presentes. A HTML-AAM define como cada elemento HTML é mapeado para um papel acessível. Já a Core-AAM 1.2 define como papéis, estados e propriedades ARIA são mapeados para as APIs de acessibilidade da plataforma.

O mapeamento do DOM para a árvore de acessibilidade não é de um para um. Uma <div> ou um <span> que existe apenas para flexbox ou estilização costuma ser achatado e desaparecer da árvore. No sentido inverso, a HTML-AAM determina que um <video> com o atributo controls expõe seus controles nativos, como reproduzir e volume, como nós filhos mapeados para papéis como button e slider. Nenhum desses controles aparece no DOM da página.

Conteúdo oculto também é removido. A WAI-ARIA 1.2 exclui elementos da árvore quando eles não são exibidos (display: none, visibility: hidden, o atributo HTML hidden) ou quando têm aria-hidden="true". Uma classe CSS “visually hidden” ou sr-only é um caso diferente: ela apenas move o conteúdo para fora da tela, então o conteúdo continua na árvore.

O que um nó acessível contém?

Cada nó da árvore de acessibilidade expõe até quatro informações: um papel (o que ele é), um nome (como ele se chama), estados (sua condição atual) e, em alguns controles, um valor. Veja um checkbox com rótulo:

<label><input type="checkbox" checked> Email me product updates</label>

No formato de ARIA snapshot do Playwright, o nó resultante fica assim (exemplo ilustrativo):

- checkbox "Email me product updates" [checked]

O papel é checkbox, o <label> fornece o nome e [checked] é o estado. Um checkbox comunica sua informação por meio do estado de marcação. O valor se aplica a controles como campos de texto e sliders, e o formato de snapshot o coloca depois de dois-pontos:

- textbox "Email": ada@example.com

Para entender como cada papel é definido e quando vale a pena adicionar papéis ARIA por conta própria, consulte Understanding Accessibility Roles in HTML.

Como o nome acessível é calculado?

De forma simplificada, o navegador obtém o nome acessível de um elemento da primeira fonte que fornecer um:

  1. aria-labelledby, apontando para o texto de outros elementos
  2. aria-label
  3. Rotulagem nativa: um elemento <label> ou o texto alt de uma imagem
  4. O próprio conteúdo textual do elemento, para papéis que permitem nomeação a partir do conteúdo (botões, links)
  5. O atributo title, como último recurso

O ARIA tem prioridade sobre a rotulagem nativa. Se um botão tem o texto visível “Send” e aria-label="Submit form", o leitor de tela anuncia “Submit form”. Um usuário de controle por voz que diga “click Send” pode não obter nenhuma correspondência. O algoritmo completo, incluindo controles incorporados e recursão, está descrito em Accessible Name and Description Computation 1.2.

Como os leitores de tela usam a árvore de acessibilidade?

Os leitores de tela não leem o DOM. Eles leem a árvore de acessibilidade por meio da API de acessibilidade do sistema operacional, que o navegador implementa. As tabelas de mapeamento da Core-AAM abrangem MSAA com IAccessible2 e UI Automation no Windows, a AX API (NSAccessibility) no macOS e ATK/AT-SPI no Linux. O leitor de tela consulta esses objetos para obter papel, nome e estado, e escuta eventos como mudanças de foco. Se uma propriedade nunca chega à árvore, o usuário nunca a ouve.

Como inspecionar a árvore de acessibilidade

O Chrome DevTools e o Firefox DevTools mostram a árvore de acessibilidade diretamente: o Chrome pela aba Accessibility do painel Elements e o Firefox pelo seu Accessibility Inspector.

Chrome: abra o painel Elements, selecione um nó e abra a aba Accessibility (ela pode estar escondida atrás do botão More Tabs »). A aba mostra o papel, o nome e as propriedades calculados, além da origem do nome. Ative Show accessibility tree para trocar a árvore do DOM no painel Elements pela árvore de acessibilidade da página inteira. A referência de acessibilidade do Chrome DevTools documenta os dois recursos. O Chrome também tem uma página interna, chrome://accessibility, para depuração no nível do navegador.

Firefox: o Accessibility Inspector pode ser aberto pelo menu de contexto da página (Inspect Accessibility Properties) ou clicando com o botão direito em um nó no painel HTML do Inspector e escolhendo Show Accessibility Properties. O inspetor exibe a própria árvore de acessibilidade do Gecko, e não informações da camada de acessibilidade da plataforma. Por isso, mostra o mesmo resultado em qualquer sistema operacional.

Dois bugs que a árvore de acessibilidade revela

A árvore de acessibilidade deixa evidentes dois bugs comuns em componentes: uma div clicável sem o papel de botão e um botão de ícone sem nome acessível. Cada problema aparece como um papel ausente ou um nome ausente. Templates em Vue e Angular produzem o mesmo resultado, porque a árvore só enxerga o DOM renderizado.

Uma div clicável sem o papel de botão

// Before
<div className="btn" onClick={save}>Save</div>

// After
<button type="button" onClick={save}>Save</button>
# Before (illustrative)
- text: Save
# After
- button "Save"

Uma <div> com um manipulador de clique não tem o papel de botão na árvore de acessibilidade. O leitor de tela não a anuncia como um controle, e o usuário de teclado não consegue chegar até ela com Tab nem acioná-la com Enter ou Espaço. Replays de sessão desse bug mostram a diferença com clareza: usuários de mouse clicam no controle sem problemas, enquanto usuários de teclado passam direto, com Tab, por algo que parece um botão mas não existe como botão na árvore.

Um botão de ícone sem nome

// Before
<button onClick={close}><svg aria-hidden="true">{/* icon */}</svg></button>

// After
<button aria-label="Close dialog" onClick={close}>
  <svg aria-hidden="true">{/* icon */}</svg>
</button>
# Before (illustrative)
- button
# After
- button "Close dialog"

Um botão só com ícone, sem texto e sem aria-label, aparece como um botão com nome vazio. Assim, o leitor de tela não tem nada a anunciar além de “botão”.

Testando a árvore de acessibilidade com Playwright

O locator getByRole do Playwright encontra elementos pelo papel ARIA, pelos atributos ARIA e pelo nome acessível, seguindo as especificações do W3C. Por padrão, ele só encontra elementos que não estão ocultos. Portanto, um teste que localiza um controle por papel e nome também verifica se o controle expõe esse papel e esse nome. Os ARIA snapshots vão além: locator.ariaSnapshot() e page.ariaSnapshot() retornam uma visão em YAML da árvore de acessibilidade, e expect(locator).toMatchAriaSnapshot() faz asserções com base nela.

import { test, expect } from '@playwright/test';

test('save control is a real button', async ({ page }) => {
  await page.goto('/settings');
  await page.getByRole('button', { name: 'Save' }).click();
  await expect(page.locator('body')).toMatchAriaSnapshot(`- button "Save"`);
  await expect(page.locator('body')).toMatchAriaSnapshot(`- button "Close dialog"`);
});

Execute esse teste contra o markup do “antes” e a chamada a getByRole falha pelo mesmo motivo que deixa um usuário de leitor de tela travado. Um template só precisa corresponder a uma parte da árvore, e um template de um único nó, como os do exemplo, corresponde em qualquer profundidade. Se um template listar vários nós no nível superior, eles precisam ter o mesmo pai e aparecer na mesma ordem em que estão na árvore. Quando um locator falhar, registre no log o resultado de await page.ariaSnapshot() para ver o que a árvore realmente contém. Esses são os nomes da API em JavaScript; os bindings das outras linguagens têm equivalentes. A própria documentação do Playwright afirma que locators baseados em papéis não substituem auditorias de acessibilidade nem testes de conformidade, então trate-os como um feedback antecipado.

Os dados de papel e nome também importam fora dos test runners. Algumas ferramentas de automação baseadas em IA leem a estrutura semântica da página, e esse é um dos motivos pelos quais os navegadores agênticos funcionam melhor com markup semântico.

Conclusão

A árvore de acessibilidade é a versão da sua interface que as tecnologias assistivas realmente recebem. Um papel ausente ou um nome vazio nela significa que o controle não funciona para esses usuários. Abra a aba Accessibility no seu componente personalizado mais usado, verifique o papel e o nome dele e transforme essa verificação em uma asserção com getByRole para que o problema não volte.

Perguntas frequentes

Adicionar role='button' a uma div resolve o problema na árvore de acessibilidade?

Só em parte. Adicionar role='button' dá à div um nó de botão na árvore de acessibilidade, então os leitores de tela a anunciam como botão, mas isso não acrescenta nenhum comportamento de botão. A div ainda precisa de tabindex='0' para entrar na ordem de Tab e de um manipulador de keydown que execute a ação com Enter e Espaço. Um elemento button nativo oferece foco e ativação por teclado por padrão.

aria-hidden='true' impede que usuários de teclado foquem um elemento?

Não. aria-hidden='true' remove um elemento e seus descendentes da árvore de acessibilidade, mas não tem efeito sobre o foco do teclado. Um link, botão ou campo dentro de um contêiner com aria-hidden ainda pode receber foco via Tab, e o usuário de teclado acaba em um controle que a tecnologia assistiva não consegue nomear. Definir aria-hidden='false' em um filho não o expõe novamente. Para ocultar conteúdo interativo de todos os usuários, use display: none ou o atributo hidden.

Como posso ler o papel e o nome acessível calculados de um elemento em testes automatizados?

Use comandos de automação em vez de scripts na página. A especificação WebDriver do W3C define os comandos Get Computed Role e Get Computed Label, que o ChromeDriver implementa e o WebdriverIO expõe como getComputedRole() e getComputedLabel(). O Playwright oferece as asserções toHaveRole() e toHaveAccessibleName() para um único elemento, além de ariaSnapshot() para uma visão em YAML de uma subárvore inteira. Todos eles informam o papel e o nome que a tecnologia assistiva recebe.

Por que as correspondências de nome do getByRole mudaram depois da atualização para o Playwright 1.65?

O Playwright 1.65 deixou de considerar, nos nomes acessíveis e nos ARIA snapshots, o texto que o navegador não renderiza. Texto que não está atribuído a um slot ou que fica diretamente dentro de um elemento details fechado não é mais contabilizado. Isso pode alterar os resultados de getByRole() com a opção name, a saída de ariaSnapshot() e as asserções de toMatchAriaSnapshot(). Por isso, os nomes esperados devem corresponder apenas ao texto que o navegador realmente renderiza.

Open-source session replay

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.