Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Regiões dinâmicas ARIA: status, alert, aria-live e aria-atomic

As regiões dinâmicas ARIA comunicam alterações às tecnologias de apoio sem deslocar o foco. Escolhe a prioridade do anúncio e a quantidade de contexto a incluir.

Versão: Current web platform; runtime support varies

Sintaxe

// Live-region roles and attributes are defined by WAI-ARIA 1.2.
role="status"  (implicit aria-live="polite", aria-atomic="true")
role="alert"   (implicit aria-live="assertive", aria-atomic="true")
aria-live="off" | "polite" | "assertive"
aria-atomic="false" | "true"

// DOM update: change the text of a node in an existing live region.
messageNode.textContent = message;

Uma região dinâmica ARIA permite que uma tecnologia de apoio, como um leitor de ecrã, anuncie alterações de conteúdo sem deslocar o foco. Estes papéis e atributos pertencem à plataforma Web, não ao ECMAScript. O JavaScript atualiza o DOM, por exemplo com textContent para uma mensagem de texto simples.

Usa role="status" para informações não urgentes, como o número de resultados. Este papel implica aria-live="polite" e aria-atomic="true". O papel role="alert" implica aria-live="assertive" e aria-atomic="true". Usa-o com moderação, apenas para mensagens urgentes que não exigem resposta. Não acrescentes aria-live="assertive" a um alerta: em algumas configurações, a redundância pode fazer com que seja anunciado duas vezes.

aria-live define a prioridade: polite espera por uma pausa adequada, assertive pode interromper o anúncio em curso e off não pede anúncios se o foco estiver fora da região. Se o foco estiver dentro da região, as alterações ainda podem ser anunciadas. aria-atomic define o âmbito, não a prioridade: true pede todo o conteúdo da região e false apenas os nós alterados. O valor geral predefinido é false, mas os dois papéis acima implicam true.

Coloca uma região vazia no DOM antes de atualizar o seu conteúdo, de preferência no HTML inicial. Não desloques o foco para lá só para anunciar uma alteração. Algumas configurações também anunciam um alerta inserido com o texto já presente, mas não contes com isso. Testa as combinações de navegador e tecnologia de apoio que suportas.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>ARIA live regions</title>
</head>
<body>
  <button type="button" id="add-result">Add result</button>
  <button type="button" id="simulate-failure">Simulate connection loss</button>
  <p id="result-status" role="status"></p>
  <p id="connection-alert" role="alert"></p>

  <script>
    const statusRegion = document.getElementById('result-status');
    const alertRegion = document.getElementById('connection-alert');
    const count = document.createElement('span');
    let total = 0;

    document.getElementById('add-result').addEventListener('click', () => {
      if (total === 0) statusRegion.append('Results: ', count);
      total += 1;
      count.textContent = String(total);
    });

    document.getElementById('simulate-failure').addEventListener('click', () => {
      alertRegion.textContent = 'Connection lost. Changes cannot be saved.';
    });
  </script>
</body>
</html>

Resultado

Initially both regions are empty.
After the first activation of Add result: Results: 1
After the second activation of Add result: Results: 2
After activating Simulate connection loss: Connection lost. Changes cannot be saved.
These are visible text updates, not a screen reader transcript.

Guarda o exemplo como ficheiro HTML e abre-o num navegador. Ativa «Add result» duas vezes e depois «Simulate connection loss». Na segunda ativação muda apenas o número, mas `status` pede a mensagem completa. O resultado é texto visível na página, não uma leitura garantida.

Lições relacionadas

  • JavaScript · Lição 23 · Intermédio · Versão: 3

Fontes