Właściwość Relacja

`aria-describedby`

Odwołuje się do identyfikatorów jednego lub więcej elementów, których tekst staje się rozszerzonym opisem tego elementu. Ogłaszany po dostępnej nazwie. Używaj dla tekstu pomocniczego, wskazówek dotyczących formatu i komunikatów błędów wyświetlanych inline.

Kiedy używać

Dla informacji uzupełniających umieszczonych obok kontrolki: wskazówka formatu pod polem daty („DD.MM.RRRR”), lista reguł dotyczących hasła, komunikat błędu wyświetlany inline, instrukcje powyżej złożonego widżetu. Etykieta odpowiada na pytanie co to jest?; opis odpowiada na pytanie co jeszcze powinienem wiedzieć?.

Stosuj na polach formularza, przyciskach, oknach dialogowych i wszelkich niestandardowych widżetach, gdzie dodatkowy kontekst powinien pojawić się po nazwie.

Jak działa

Wartość to lista identyfikatorów elementów oddzielona spacjami, o takiej samej budowie jak aria-labelledby. Czytniki ekranu ogłaszają opis po dostępnej nazwie i roli, zwykle po krótkiej pauzie — „E-mail, pole edycji, Skontaktujemy się z Tobą wyłącznie w sprawie tego zamówienia.” Wiele identyfikatorów jest łączonych w podanej kolejności.

Opis to nie nazwa. Nie pojawia się w polu nazwy drzewa dostępności, więc axe-core nie uzna go za oznaczenie kontrolki. Jeśli kontrolka nie ma nazwy, aria-describedby jej nie zastąpi.

Gdy opis ulega zmianie (np. pojawia się błąd), zaktualizuj treść tekstową wskazywanego elementu zamiast zamieniać wartość aria-describedby — wiele technologii wspomagających nie powtarza komunikatu przy zmianie samego atrybutu, ale powtarza go, gdy wskazywany tekst jest częścią regionu live lub gdy fokus ponownie trafia na pole.

Typowe błędy

Użycie aria-describedby zamiast nazwy. Kontrolka nadal nie ma etykiety; użytkownik słyszy opis, ale nigdy nazwę.
Wskazywanie na identyfikator, który nie istnieje lub został usunięty z DOM przez renderowanie.
Dodawanie aria-describedby do elementu niemożliwego do sfokusowania. Większość przeglądarek eksponuje opis tylko wtedy, gdy element uzyska fokus lub zostanie bezpośrednio odpytany.
Długi tekst marketingowy jako opis — obszerne komunikaty skłaniają użytkowników do globalnego wyłączania opisów.
Zapominanie o powiązaniu komunikatów błędów inline w formularzu. aria-describedby="email-error" wraz z aria-invalid="true" to kanoniczny wzorzec; bez tego odwołania błąd jest widoczny, ale niemy.
Używanie tego samego identyfikatora opisu dla wielu pól za pomocą aria-describedby="hint" — działa, ale sprawdź, czy ten sam tekst rzeczywiście dotyczy każdego pola.

Przykład

<label for="password">Password</label>
<input
  id="password"
  type="password"
  aria-describedby="pw-rules pw-error"
  aria-invalid="true"
>
<p id="pw-rules">At least 12 characters, including a number.</p>
<p id="pw-error">Password is too short.</p>