0Pricing
HTML Academy · Aula

aria-expanded e aria-controls para alternâncias

Crie componentes acessíveis de divulgação e acordeões com ARIA.

aria-expanded e aria-controls para alternâncias é uma aula grátis de HTML Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de HTML Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de HTML Academy inclui 4 aulas no total.

Visão geral do padrão de alternância

Controles de alternância (acordeões, menus suspensos e menus) precisam de ARIA para comunicar seu estado aberto ou fechado:

  • aria-expanded — indica o estado aberto ou fechado de um controle
  • aria-controls — vincula o controle ao elemento que ele controla

aria-expanded

aria-expanded comunica se um elemento controlado está expandido ou recolhido:

<button aria-expanded="false" aria-controls="menu">
  Menu
</button>
<ul id="menu" hidden>
  <li><a href="/">Home</a></li>
</ul>
<script>
btn.addEventListener('click', () => {
  const expanded = btn.getAttribute('aria-expanded') === 'true';
  btn.setAttribute('aria-expanded', !expanded);
  menu.hidden = expanded;
});
</script>

aria-controls

aria-controls faz referência ao id do elemento que é controlado:

<button
  id="details-btn"
  aria-expanded="false"
  aria-controls="details-panel"
>
  Show Details
</button>
<div id="details-panel" hidden>
  <p>Additional details go here...</p>
</div>
<!-- Screen reader: 'Show Details, button, collapsed'
     After click: 'Show Details, button, expanded' -->

Padrão de acordeão

Acordeão acessível com aria-expanded:

<div class="accordion">
  <h3>
    <button
      aria-expanded="false"
      aria-controls="panel-1"
    >Section 1</button>
  </h3>
  <div id="panel-1" hidden>
    <p>Panel 1 content...</p>
  </div>

  <h3>
    <button
      aria-expanded="false"
      aria-controls="panel-2"
    >Section 2</button>
  </h3>
  <div id="panel-2" hidden>
    <p>Panel 2 content...</p>
  </div>
</div>

Padrão de menu suspenso

Menu suspenso de navegação acessível:

<nav>
  <button
    aria-expanded="false"
    aria-haspopup="true"
    aria-controls="products-menu"
  >Products</button>

  <ul id="products-menu" role="menu" hidden>
    <li role="menuitem"><a href="/widget">Widget</a></li>
    <li role="menuitem"><a href="/gadget">Gadget</a></li>
  </ul>
</nav>

aria-haspopup

aria-haspopup indica que a ativação do controle abrirá uma janela sobreposta:

<button aria-haspopup="menu">File</button>
<!-- Values: true (menu), menu, listbox, tree, grid, dialog -->
<!-- Screen reader: 'File, button, has popup' -->

<!-- Note: aria-haspopup="true" is equivalent to "menu" -->
<!-- Use specific values when the popup type matters -->

Complemento ARIA para Details/Summary

Os elementos nativos details/summary já comunicam o estado de expansão — não é necessário usar ARIA:

<details>
  <summary>FAQ Question</summary>
  <p>Answer goes here.</p>
</details>
<!-- Browser automatically provides aria-expanded
     and the disclosure widget semantics -->
<!-- No need to add aria-expanded manually to summary -->

CSS para o estado aria-expanded

Use aria-expanded como um gancho de CSS:

/* Panel hidden by default: */
[aria-controls] + [hidden] {
  display: none;
}

/* Or using aria-expanded on the button: */
[aria-expanded="false"] + .panel {
  display: none;
}

[aria-expanded="true"] + .panel {
  display: block;
}

/* Rotate arrow icon: */
[aria-expanded="true"] .arrow {
  transform: rotate(180deg);
}

Requisitos de teclado para controles de alternância

Os componentes de alternância devem oferecer interação pelo teclado:

  • Enter ou Espaço — ativar o botão de alternância
  • Escape — fechar um menu suspenso ou menu
  • Teclas de seta — navegar dentro de um menu aberto

Gerenciamento do foco após a alternância

Depois de alternar o conteúdo, gerencie o foco adequadamente:

// Accordion: focus stays on the button (usually OK)
// Dropdown menu: move focus to first menu item on open

button.addEventListener('click', () => {
  const expanded = button.getAttribute('aria-expanded') === 'true';
  button.setAttribute('aria-expanded', !expanded);
  panel.hidden = expanded;

  if (!expanded) {
    // Opening a dropdown: focus first item
    panel.querySelector('a, button, [tabindex]')?.focus();
  }
});

Considerações para dispositivos móveis

Componentes de alternância em dispositivos móveis:

  • Os alvos de toque devem ter pelo menos 44×44px (WCAG 2.5.5)
  • aria-expanded é compatível com leitores de tela móveis (VoiceOver no iOS e TalkBack no Android)
  • Gestos de deslizar não substituem a ativação pelo teclado ou por botão

Verificação rápida

Qual valor aria-expanded deve ter quando a seção controlada está oculta?

Recapitulação: aria-expanded e aria-controls

Elementos essenciais de ARIA para alternâncias:

  • aria-expanded="true/false" — estado aberto ou fechado do controle
  • aria-controls="id" — vincula o controle ao seu painel
  • aria-haspopup — indica que há uma janela sobreposta disponível
  • Atualize aria-expanded a cada alternância
  • Mova o foco para dentro do menu aberto; devolva-o ao acionador ao fechar

Perguntas Frequentes

A aula “aria-expanded e aria-controls para alternâncias” é grátis?

Sim — o texto completo de “aria-expanded e aria-controls para alternâncias” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de HTML Academy, atualize para CoddyKit PRO. O curso de HTML Academy inclui 4 aulas no total.

O que vou aprender em “aria-expanded e aria-controls para alternâncias”?

Crie componentes acessíveis de divulgação e acordeões com ARIA. Você pratica HTML Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar HTML Academy?

Nenhuma experiência prévia é necessária. HTML Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “aria-expanded e aria-controls para alternâncias”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de HTML Academy?

Sim. Cada aula de HTML Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. aria-expanded e aria-controls para alternâncias
  2. aria-selected e padrões de abas
  3. Regiões dinâmicas: aria-live aria-atomic aria-relevant
  4. Testes com leitores de tela
← Voltar para HTML Academy