Normativas · ARIA

Rol Control

progressbar

Marca un elemento como indicador de progreso. Se recomienda usar <progress> en primer lugar, ya que incluye semántica, representación visual y atributos de valor de forma nativa. Solo se debe recurrir a role="progressbar" cuando sea necesario aplicar estilos más allá de lo que permite el elemento nativo.

Cuándo utilizarlo

Se debe usar <progress value="42" max="100">. El elemento nativo es difícil de estilizar de manera consistente entre navegadores, que es la principal razón para recurrir a role="progressbar" sobre un <div> personalizado.

Dos variantes:

  • Determinado — se conoce el total. Se deben establecer aria-valuemin, aria-valuemax y actualizar aria-valuenow conforme avanza el proceso.
  • Indeterminado — no se conoce el total. Se omite aria-valuenow (o no se establece). El lector de pantalla anuncia «ocupado» / «cargando» sin un porcentaje.

Se debe establecer aria-valuetext cuando el número en bruto no sea significativo; por ejemplo, aria-valuetext="Uploading photo 3 of 8" resulta más claro que «37 por ciento».

Una barra de progreso NO es una región en vivo: los lectores de pantalla no anuncian cada cambio en aria-valuenow. Si se necesita que el cambio sea verbalizado, también se debe usar role="status" en un elemento auxiliar con el texto de progreso legible por humanos.

Errores frecuentes

  • role="progressbar" en un indicador giratorio sin aria-label. Se anuncia el rol, pero no hay nombre para la tarea.
  • Usar role="progressbar" para un indicador giratorio indeterminado y establecer simultáneamente aria-valuenow="0". Eso anuncia «0 por ciento completado» de forma indefinida.
  • Olvidar eliminar la barra de progreso (o su aria-busy) cuando el proceso termina. Algunos lectores de pantalla continúan consultando el estado.
  • Combinar una barra de progreso con un porcentaje oculto visualmente sin actualizar ninguno de los dos cuando la carga se detiene. Los usuarios quedan atrapados en un estado bloqueado sin anuncio alguno.
  • Aplicar role="progressbar" tanto al contenedor envolvente como a la barra de relleno interior. Roles duplicados; se debe elegir uno.

Ejemplo

<!-- Recomendado -->
<label for="upload">Uploading</label>
<progress id="upload" value="42" max="100">42%</progress>

<!-- Determinado personalizado -->
<div id="uploadLabel">Uploading photo 3 of 8</div>
<div
  role="progressbar"
  aria-labelledby="uploadLabel"
  aria-valuemin="0"
  aria-valuemax="100"
  aria-valuenow="37"
></div>