Rooli Widget

`checkbox`

Merkitsee elementin kaksi- tai kolmitilaiseksi valintaruuduksi. Käytä ensin <input type="checkbox">; turvaudu role="checkbox"-attribuuttiin vain kun natiivielementti on mahdoton — esimerkiksi rakennettaessa kolmitilaista ohjauselementtiä, joka voi näyttää sekaarvon.

Milloin käyttää

Käytä <input type="checkbox">. Natiivielementti tarjoaa kohdistuksen, Space-aktivoinnin, :checked-pseudoluokan, lomakkeen lähetyksen ja indeterminate JS-ominaisuuden kolmitilaista käyttöä varten. role="checkbox" on tarkoitettu kahteen tapaukseen:

Tarvitset kolmitilaisen valintaruudun, joka paljastuu arvona aria-checked="mixed" (“valitse kaikki” -toiminto, joka heijastaa lasten tilaa).
Suunnittelujärjestelmä toimittaa mukautetun valintaruutukomponentin, jota ei voi korvata.

Jos toteutat role="checkbox" -attribuutin muulle kuin input-elementille, sinun täytyy asettaa aria-checked (se on pakollinen), hallita tabindex="0" ja käsitellä Space-näppäimen keydown-tapahtuma.

Näppäimistö- ja kohdistussopimus

APG-valintaruutukuvion mukaisesti:

Tab siirtää kohdistuksen valintaruutuun.
Space vaihtaa aria-checked-arvoa "true":n ja "false":n välillä (ja "mixed":iin kolmitilaisessa).
Enter EI aktivoi valintaruutua — vain Space. (Natiivit input-elementit myös jättävät Enter-näppäimen huomiotta useimmissa selaimissa.)

Kohdistus pysyy valintaruudussa aktivoinnin jälkeen.

Yleisiä virheitä

role="checkbox" ilman aria-checked-attribuuttia. Tila vaaditaan heti, kun elementti on DOM:ssa.
aria-checked="true":n käyttö ainoastaan luokkakoukuna — visuaalin päivittäminen mutta attribuutin päivittämättä jättäminen klikkauksen yhteydessä.
Mukautetut valintaruudut, jotka reagoivat klikkaukseen mutta eivät Space-näppäimeen.
Natiivin <input>-elementin pakkaaminen <div role="checkbox">:n sisään — päällekkäinen semantiikka hämmentää ruudunlukuohjelmia.
Kolmitilaiset ohjauselementit, jotka kierrättävät Space-näppäimellä: false → true → mixed → false. APG määrittää false → true → false; mixed asetetaan ohjelmallisesti sivulta, ei käyttäjän toimesta.

Esimerkki

<!-- Suositeltava -->
<label>
  <input type="checkbox" name="terms" required>
  Hyväksyn käyttöehdot
</label>

<!-- Mukautettu kolmitilainen "valitse kaikki" -->
<div
  role="checkbox"
  tabindex="0"
  aria-checked="mixed"
  aria-labelledby="selectAllLabel"
>
</div>
<span id="selectAllLabel">Valitse kaikki rivit</span>