aria-level

Quando si usa

Su role="heading" per dichiarare il livello del titolo — l’equivalente ARIA della scelta tra <h1> e <h6>. Gli elementi di intestazione nativi devono rappresentare la prima scelta; si ricorre a role="heading" + aria-level solo quando occorre un livello superiore a 6, o quando un framework non consente di usare direttamente un elemento di intestazione.

È valido anche su role="treeitem" (profondità nell’albero, a partire da 1 per gli elementi di primo livello) e su role="listitem" all’interno di un role="list" annidato, quando la nidificazione non è espressa dalla struttura del DOM.

Comportamento

Il valore è un intero positivo. Per le intestazioni, i valori da 1 a 6 corrispondono a <h1>–<h6>; i valori superiori a 6 sono validi in ARIA, ma pochi screen reader li espongono, pertanto non è opportuno dipendere dal fatto che il livello 7 venga annunciato come tale.

Per gli elementi ad albero, il livello indica la profondità: la radice dell’albero è al livello 1, i suoi figli diretti al livello 2 e così via. Il numero di livello consente all’utente di uno screen reader di comprendere la propria posizione nella gerarchia senza percepire l’indentazione visiva.

L’attributo non modifica lo stile visivo. Se un «titolo ARIA di livello 4» deve apparire come un h4, lo stile va applicato manualmente.

Errori comuni

• Usare role="heading" con aria-level="3" anziché semplicemente <h3>. L’elemento nativo fornisce gratuitamente il role, il livello, la navigazione da tastiera predefinita e l’integrazione nella struttura del documento.
• Impostare aria-level su un elemento privo di role="heading", role="treeitem" o role="listitem". L’attributo non ha effetto, ad esempio, su un <button> o un <div> senza role.
• Saltare un livello — un livello 2 seguito da un livello 4 altera la struttura del documento e viene rilevato durante gli audit del criterio di successo 1.3.1.
• Treeitem con livello errato: ogni figlio di un elemento di livello 2 deve essere al livello 3. Errori di scarto qui compromettono gli annunci «salito di un livello» / «sceso di un livello».
• Valori non interi o pari a zero. Sono validi solo gli interi positivi; aria-level="0" viene ignorato.
• Dimenticare di aggiornare aria-level quando gli elementi vengono spostati in un albero con trascinamento.

Esempio

<!-- Intestazione più profonda di h6 (raro; necessario in strutture complesse) -->
<div role="heading" aria-level="7">Sotto-sotto-sotto-sezione</div>

<!-- I treeitem esprimono la profondità tramite aria-level -->
<ul role="tree">
  <li role="treeitem" aria-level="1" aria-expanded="true">
    Documenti
    <ul>
      <li role="treeitem" aria-level="2">Fatture</li>
      <li role="treeitem" aria-level="2">Contratti</li>
    </ul>
  </li>
</ul>