Standardy · ARIA

Rola Widget złożony

listbox

Oznacza element jako listę wybieralnych opcji. Używaj <select> w prostym przypadku jednokrotnego wyboru — zapewnia przyjazny mobilnie selektor i pełną obsługę klawiatury. Sięgaj po role="listbox" gdy potrzebujesz niestandardowego stylowania, wielokrotnego wyboru lub parowania z comboboxem.

Kiedy używać

Używaj <select> (jednokrotny wybór) lub <select multiple> gdy tylko jest to możliwe. Natywny element dostarcza cały model interakcji, w tym obsługę klawiatury zgodną z platformą.

role="listbox" jest odpowiednie gdy:

  • Listbox jest wyskakującym okienkiem niestandardowego comboboxa.
  • Potrzebujesz bogatej zawartości opcji (ikony, tekst dodatkowy), której <select> nie może wyrenderować.
  • Potrzebujesz wielokrotnego wyboru z niestandardowym stylowaniem znaczników.
  • Budujesz listę transferu lub filtrowalny selektor.

Dzieci muszą mieć role="option" (z dozwolonym role="group" jako pośrednim wrapperem do sekcjonowania). Ustaw aria-multiselectable="true" dla listboxów wielokrotnego wyboru.

Kontrakt klawiatura + fokus

Zgodnie z wzorcem APG listbox:

  • Tab przenosi fokus na listbox; Tab przenosi fokus poza. Wewnątrz listboxa fokus pozostaje na kontenerze, a „aktywna” opcja jest śledzona przez aria-activedescendant.
  • Strzałki góra/dół przesuwają aktywną opcję.
  • Home / End przeskakują do pierwszej / ostatniej.
  • Jednokrotny wybór: każde naciśnięcie strzałki zaznacza też aktywną opcję.
  • Wielokrotny wybór: Spacja przełącza zaznaczenie aktywnej opcji; Shift+Strzałka rozszerza ciągły zakres; Ctrl/Cmd+A zaznacza wszystkie.
  • Typeahead: wpisanie litery przeskakuje do następnej opcji zaczynającej się od tej litery.

Typowe błędy

  • Przenoszenie fokusu DOM do każdej opcji zamiast używania aria-activedescendant. Psuje typeahead i integrację z comboboxem.
  • Dzieci role="option" bez atrybutów id — aria-activedescendant nie może ich wskazać.
  • Listbox wielokrotnego wyboru bez aria-multiselectable="true". Czytniki ekranu ogłaszają go jako jednokrotny wybór.
  • Listbox posiada opcje istniejące w innym miejscu DOM bez użycia aria-owns do wyraźnego zaznaczenia relacji.
  • Używanie role="listbox" dla statycznej listy elementów tylko do odczytu. To role="list", nie listbox — listbox implikuje interaktywność.

Przykład

<label id="topicsLabel">Wybierz swoje tematy</label>
<ul
  role="listbox"
  aria-labelledby="topicsLabel"
  aria-multiselectable="true"
  tabindex="0"
  aria-activedescendant="topic-1"
>
  <li id="topic-1" role="option" aria-selected="true">Dostępność</li>
  <li id="topic-2" role="option" aria-selected="false">Technologie asystujące</li>
  <li id="topic-3" role="option" aria-selected="true">Standardy</li>
</ul>