Standardit · ARIA

Rooli Yhdistelmäwidget

listbox

Merkitsee elementin valittavien vaihtoehtojen luetteloksi. Yksinkertaisessa yhden valinnan tilanteessa käytä <select>-elementtiä — se tarjoaa mobiiliystävällisen valitsimen ja täyden näppäimistötuen. Käytä role="listbox" mukautettuun tyylittelyyn, monivalintaan tai yhdistettynä combobox-komponenttiin.

Milloin käyttää

Käytä <select>:a (yksi valinta) tai <select multiple>:a aina kun mahdollista. Natiivielementti toimittaa koko vuorovaikutusmallin, mukaan lukien alustakohtaisen näppäimistönkäsittelyn.

role="listbox" on sopiva, kun:

  • Listbox on mukautetun combobox-komponentin ponnahdusikkuna.
  • Tarvitaan rikkaampaa vaihtoehtojen sisältöä (kuvakkeet, toissijainen teksti), jota <select> ei tue.
  • Tarvitaan monivalinta mukautetuilla valintamerkkityyleillä.
  • Rakennetaan siirtoluettelo tai suodatettava valitsin.

Lasten on oltava role="option" (välitasolla role="group" on sallittu ryhmittelyyn). Aseta aria-multiselectable="true" monivalintalistboxille.

Näppäimistö- ja kohdistussopimus

APG listbox -mallin mukaan:

  • Tab siirtää kohdistuksen listboxiin; Tab siirtää ulos. Listboxin sisällä kohdistus pysyy säilössä ja aktiivinen vaihtoehto seurataan aria-activedescendant:lla.
  • Ylös/alas-nuolet siirtävät aktiivista vaihtoehtoa.
  • Home / End hyppää ensimmäiseen / viimeiseen.
  • Yksi valinta: nuolenpainallus valitsee myös aktiivisen vaihtoehdon.
  • Monivalinta: Välilyönti vaihtaa aktiivisen vaihtoehdon valinnan; Shift+Nuoli laajentaa jatkuvan valinnan; Ctrl/Cmd+A valitsee kaikki.
  • Kirjoitusennakko: kirjaimen painaminen hyppää seuraavaan sillä alkavaan vaihtoehtoon.

Yleiset virheet

  • DOM-kohdistuksen siirtäminen jokaiseen vaihtoehtoon aria-activedescendant:n sijaan. Rikkoo kirjoitusennakon ja combobox-integraation.
  • role="option"-lapset ilman id-attribuutteja — aria-activedescendant ei voi viitata niihin.
  • Monivalintalistbox, josta puuttuu aria-multiselectable="true". Ruudunlukuohjelmat ilmoittavat sen yksivalintana.
  • Listbox omistaa vaihtoehtoja, jotka sijaitsevat muualla DOM:ssa ilman aria-owns-suhteen määrittelyä.
  • role="listbox":n käyttö staattisten vain-luku-kohteiden listalle. Se on role="list", ei listbox — listbox edellyttää interaktiivisuutta.

Esimerkki

<label id="topicsLabel">Valitse aiheet</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">Saavutettavuus</li>
  <li id="topic-2" role="option" aria-selected="false">Avustava teknologia</li>
  <li id="topic-3" role="option" aria-selected="true">Standardit</li>
</ul>