aria-level

Cuándo utilizarlo

Se utiliza en role="heading" para declarar la profundidad del encabezado, que es el equivalente ARIA de elegir entre <h1> y <h6>. Los elementos de encabezado nativos deben ser la opción predeterminada; se debe recurrir a role="heading" + aria-level únicamente cuando se necesite un nivel superior a 6 o cuando las restricciones del framework impidan el uso del elemento de encabezado nativo.

También es válido en role="treeitem" (profundidad en el árbol, comenzando en 1 para los elementos de nivel superior) y en role="listitem" dentro de un role="list" anidado cuando el anidamiento no queda expresado por la estructura del DOM.

Comportamiento

El valor debe ser un número entero positivo. En el caso de los encabezados, los valores del 1 al 6 se corresponden con <h1>–<h6>; los valores superiores a 6 son válidos en ARIA, pero solo algunos lectores de pantalla los anuncian como tales, por lo que no conviene depender de que el nivel 7 sea anunciado como tal.

Para los elementos de árbol, el nivel equivale a la profundidad: la raíz de un árbol es el nivel 1, sus hijos directos son el nivel 2, y así sucesivamente. El número de nivel permite al usuario de un lector de pantalla comprender en qué punto de la jerarquía se encuentra sin necesidad de ver la sangría visual.

El atributo no modifica el estilo visual. Si un «encabezado ARIA de nivel 4» debe tener la apariencia de un h4, el estilo debe aplicarse de forma explícita.

Errores frecuentes

• Usar role="heading" con aria-level="3" en lugar de simplemente <h3>. El elemento nativo proporciona el rol, el nivel, la navegación por teclado predeterminada y la integración con el esquema del documento de forma gratuita.
• Establecer aria-level en un elemento que no tiene role="heading", role="treeitem" ni role="listitem". El atributo no tiene ningún efecto en, por ejemplo, un <button> o un <div> sin rol.
• Saltarse un nivel: pasar del nivel 2 directamente al nivel 4 confunde el esquema del documento y es detectado por las auditorías del criterio 1.3.1.
• Elementos de árbol con el nivel incorrecto: todos los hijos de un elemento de nivel 2 deben ser de nivel 3. Los errores de un nivel en más o en menos rompen los anuncios de «subió un nivel» y «bajó un nivel».
• Valores no enteros o iguales a cero. Solo son válidos los enteros positivos; aria-level="0" es ignorado.
• Olvidar actualizar aria-level cuando los elementos se reorganizan en un árbol con funcionalidad de arrastrar y soltar.

Ejemplo

<!-- Encabezado más profundo que h6 (poco frecuente; necesario en esquemas complejos) -->
<div role="heading" aria-level="7">Sub-sub-subsección</div>

<!-- Los elementos de árbol expresan la profundidad mediante aria-level -->
<ul role="tree">
  <li role="treeitem" aria-level="1" aria-expanded="true">
    Documentos
    <ul>
      <li role="treeitem" aria-level="2">Facturas</li>
      <li role="treeitem" aria-level="2">Contratos</li>
    </ul>
  </li>
</ul>