Właściwość Relacja

`aria-labelledby`

Odwołuje się do jednego lub więcej identyfikatorów elementów, których widoczny tekst staje się dostępną nazwą tego elementu. Preferowane względem aria-label, gdy tekst na ekranie już opisuje element sterujący.

Kiedy używać

Gdy widoczny fragment tekstu na stronie już opisuje element — nagłówek powyżej dialogu, nagłówek kolumny nad komórką, akapit wprowadzający region. aria-labelledby wskazuje na ten tekst, by czytnik ekranu ogłosił go jako dostępną nazwę elementu. Użytkownik słyszy dokładnie to, co czyta użytkownik widzący.

Natywnym odpowiednikiem w HTML jest <label for="…"> na polach formularza. aria-labelledby rozszerza tę samą ideę na każdą rolę obsługującą nazwę.

Działanie

Wartością jest rozdzielona spacjami lista identyfikatorów elementów. AT zbiera treść tekstową każdego wskazanego elementu, w kolejności, łączy je spacjami i używa wyniku jako dostępnej nazwy. Odwołania do ukrytych elementów (display: none, hidden) nadal wnoszą swój tekst — element musi jedynie istnieć w DOM.

aria-labelledby ma pierwszeństwo przed aria-label, które z kolei ma pierwszeństwo przed widocznym tekstem wewnętrznym. Jeśli więc wskazujesz na widoczny nagłówek, nie potrzebujesz dodatkowo aria-label.

Aby relacja pozostała prawidłowa: wskazane identyfikatory muszą istnieć na stronie, być unikalne, a tekst wewnątrz nich musi pozostać znaczący. Jeśli ponownie renderujesz panel zakładek i ponownie używasz identyfikatorów, sprawdź, czy nowa treść nadal opisuje etykietowany element.

Typowe błędy

Wskazywanie na identyfikator, który nie istnieje (literówka, element usunięty, komponent odmontowany). Relacja cicho się nie udaje, a element pozostaje bez nazwy.
Używanie tego samego identyfikatora dwa razy na stronie — liczy się tylko pierwsze wystąpienie.
Odwoływanie się do elementu, którego tekst jest pusty lub składa się wyłącznie z białych znaków.
Konkatenacja w złej kolejności: aria-labelledby="nazwisko imie" daje „Kowalski Jan” zamiast „Jan Kowalski”.
Wskazywanie na generyczny <div> zawierający długi akapit — cały akapit staje się nazwą. Nazwy powinny być krótkie; obszerny kontekst trafia do aria-describedby.
Zapomnienie o aktualizacji wskazanego tekstu podczas lokalizacji — nazwy desynchronizują się z widocznym interfejsem.

Przykład

<h2 id="billing-heading">Adres rozliczeniowy</h2>
<div role="group" aria-labelledby="billing-heading">
  <label>
    Ulica
    <input type="text" autocomplete="street-address">
  </label>
  <!-- … -->
</div>

<!-- Dwa identyfikatory połączone dla wzorca „imię + nazwisko" -->
<span id="first">Imię</span>
<span id="last">(wymagane)</span>
<input type="text" aria-labelledby="first last">