aria-labelledby

Quando utilizzarlo

Quando un testo visibile sulla pagina descrive già l’elemento — un’intestazione sopra una finestra di dialogo, un’intestazione di colonna sopra una cella, un paragrafo che introduce una regione. aria-labelledby punta a quel testo in modo che lo screen reader lo annunci come nome accessibile dell’elemento. L’utente sente esattamente ciò che un utente vedente legge.

L’equivalente HTML nativo è <label for="…"> sugli input di modulo. aria-labelledby estende la stessa idea a qualsiasi role che supporta un nome.

Come si comporta

Il valore è un elenco di ID elemento separati da spazi. La tecnologia assistiva raccoglie il contenuto testuale di ogni elemento referenziato, nell’ordine indicato, li unisce con spazi e usa il risultato come nome accessibile. I riferimenti a elementi nascosti (display: none, hidden) contribuiscono comunque con il loro testo — l’elemento deve semplicemente essere presente nel DOM.

aria-labelledby ha la precedenza su aria-label, che a sua volta ha la precedenza sul testo interno visibile. Pertanto, se si punta all’intestazione visibile, non è necessario aggiungere anche un aria-label.

Per mantenere la relazione valida: gli ID referenziati devono esistere nella pagina, devono essere univoci e il testo al loro interno deve rimanere significativo. Se si esegue il re-rendering di un pannello a schede riutilizzando gli ID, è necessario verificare che il nuovo contenuto descriva ancora l’elemento etichettato.

Errori comuni

• Puntare a un ID che non esiste (errore di battitura, elemento rimosso, componente smontato). La relazione fallisce silenziosamente e l’elemento risulta privo di nome.
• Riutilizzare lo stesso ID due volte nella pagina — conta solo il primo match.
• Referenziare un elemento il cui testo è vuoto o composto solo da spazi.
• Concatenazione nell’ordine sbagliato: aria-labelledby="cognome nome" produce «Rossi Mario» quando si voleva «Mario Rossi».
• Puntare a un <div> generico contenente un paragrafo lungo — l’intero paragrafo diventa il nome. I nomi devono essere brevi; il contesto lungo appartiene ad aria-describedby.
• Dimenticare di aggiornare il testo referenziato durante la localizzazione — i nomi si desincronizzano dall’interfaccia visibile.

Esempio

<h2 id="billing-heading">Indirizzo di fatturazione</h2>
<div role="group" aria-labelledby="billing-heading">
  <label>
    Via
    <input type="text" autocomplete="street-address">
  </label>
  <!-- … -->
</div>

<!-- Due ID concatenati per uno schema «nome + cognome» -->
<span id="first">Nome</span>
<span id="last">(obbligatorio)</span>
<input type="text" aria-labelledby="first last">