Normative · ARIA

Ruolo Widget

progressbar

Contrassegna un elemento come indicatore di avanzamento. Si preferisca <progress> — fornisce la semantica, il visual determinato e gli attributi di valore nativamente. Si ricorra a role="progressbar" solo quando è necessario uno stile non consentito dall'elemento nativo.

Quando utilizzarlo

Si usi <progress value="42" max="100">. L’elemento nativo è difficile da stilizzare in modo coerente tra i browser, ed è questo il motivo principale per ricorrere a role="progressbar" su un <div> personalizzato.

Due varianti:

  • Determinato — si conosce il totale. Si impostino aria-valuemin, aria-valuemax e si aggiorni aria-valuenow man mano che l’elaborazione avanza.
  • Indeterminato — non si conosce il totale. Si ometta aria-valuenow (o non lo si imposti). Lo screen reader annuncia «occupato» / «caricamento» senza una percentuale.

Si imposti aria-valuetext quando il numero grezzo non è significativo — ad esempio aria-valuetext="Caricamento foto 3 di 8" risulta più chiaro di «37 percento».

Una progressbar NON è una live region — gli screen reader non annunciano ogni modifica di aria-valuenow. Se si desidera che il cambiamento venga letto ad alta voce, si usi anche role="status" su un elemento companion contenente il testo di avanzamento leggibile dall’utente.

Errori comuni

  • role="progressbar" su uno spinner privo di aria-label. Il role viene annunciato ma non esiste un nome per l’operazione in corso.
  • Usare role="progressbar" per uno spinner indeterminato E impostare aria-valuenow="0". Questo annuncia «0 percento completato» in modo permanente.
  • Dimenticare di rimuovere la progressbar (o il suo aria-busy) al termine dell’elaborazione. Alcuni screen reader continuano a eseguire il polling.
  • Abbinare una progressbar con una percentuale visivamente nascosta senza aggiornare nessuno dei due quando il caricamento si blocca. Gli utenti ricevono uno stato bloccato senza alcun annuncio.
  • Inserire role="progressbar" sia sul contenitore esterno sia sulla barra di riempimento interna. Ruoli duplicati: se ne scelga uno solo.

Esempio

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

<!-- Determinato personalizzato -->
<div id="uploadLabel">Caricamento foto 3 di 8</div>
<div
  role="progressbar"
  aria-labelledby="uploadLabel"
  aria-valuemin="0"
  aria-valuemax="100"
  aria-valuenow="37"
></div>