ARIA-roolit, -tilat ja -ominaisuudet

Reaaliaikainen alue, joka välittää kiireellisen, aikakriittisen viestin. Ruudunlukuohjelmat ilmoittavat sen välittömästi keskeyttäen meneillään olevan puheen. Käytä harkiten — varaa aidoille virheille ja varoituksille; väärinkäyttö aiheuttaa avustavan teknologian käyttöväsymystä.

Dialogi, joka välittää kiireellisen viestin ja vaatii käyttäjän vastauksen. Yhdistää dialogin semantiikan ja hälytysilmoituksen. Käytä vain tuhoaville vahvistuksille, työtä estäville virheille tai muille keskeytyksille, jotka eivät voi odottaa.

Merkitsee itsenäisen kokonaisuuden, joka voisi seistä yksinään — blogikirjoituksen, uutisen, foorumivastauk­sen tai tuotekortin. Käytä ensin natiivia <article>-elementtiä; turvaudu role="article"-attribuuttiin vain, kun HTML-elementtiä ei voi käyttää.

Natiivi HTML: <article>

Koko sivuston ylätunnistemaamerkkialue — sisältää tyypillisesti logon, ensisijaisen navigoinnin ja haun. Ylimmän tason <header>-elementti saa tämän roolin automaattisesti. Sivulla voi olla vain yksi banner.

Natiivi HTML: <header> (top-level)

Merkitsee elementin painikkeeksi — ohjauselementiksi, joka käynnistää toiminnon aktivoituessaan. Käytä ensin natiivia HTML:n <button>-elementtiä; turvaudu role="button"-attribuuttiin <div>- tai <span>-elementissä vain, jos natiivielementti on mahdoton.

Natiivi HTML: <button>

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.

Natiivi HTML: <input type="checkbox">

Merkitsee tekstisyötteen, joka on yhdistetty ponnahduslistaukseen — käytetään automaattitäydennyksessä, ennustavan haun syötteissä ja mukautetuissa valintaelementeissä. Natiivi <select> kattaa yksinkertaisen yhden valinnan; role="combobox" tarvitaan vain suodatukseen, mukautettuun renderointiin tai etähakuehdotuksiin.

Natiivi HTML: <select>

Kiintopiste sisällölle, joka tukee pääsisältöä mutta on merkityksellinen myös yksinään — sivupalkit, aiheeseen liittyvien artikkeleiden ruudut, täydentävät kutsut. <aside>-elementti kantaa tämän roolin, kun se on ylimmällä tasolla.

Natiivi HTML: <aside>

Koko sivuston alatunnisteen kiintopiste — tekijänoikeudet, yhteystiedot, oikeudelliset linkit. Ylimmän tason <footer>-elementti kantaa tämän roolin automaattisesti. Vain yksi contentinfo per sivu.

Natiivi HTML: <footer> (top-level)

Merkitsee elementin termin määritelmäksi. Yhdistä role="term"-rooliin (tai natiivin <dfn>-elementin kanssa) termin ja määritelmän liittämiseksi. Käytä ensin natiiveja <dl>/<dt>/<dd>- tai <dfn>-elementtejä — ne kantavat semantiikan valmiina.

Natiivi HTML: <dfn>

Merkitsee säilön modaaliseksi tai ei-modaaliseksi dialogiksi. Käytä natiivista <dialog>-elementtiä showModal()-metodin kanssa — se hoitaa kohdistuseristyksen, yläkerroksen, taustan ja Escape-sulkemisen automaattisesti. Turvaudu role="dialog"-rooliin vain, kun natiivi elementti on mahdoton.

Natiivi HTML: <dialog>

Merkitsee itsenäisen havainnollistavan lohkon — kuvan, kaavion, koodilistauksen — tyypillisesti kuvatekstin kera. Käytä ensin natiivista <figure>-elementtiä; turvaudu role="figure"-rooliin vain, kun isäntäelementti ei voi olla <figure>.

Natiivi HTML: <figure>

Lomakkeen maamerkkirooli — syöttöohjauselementtien kokoelma, joka lähettää tietoja. <form>-elementti näkyy lomakemaamerkkinä VAIN, kun sillä on saavutettava nimi. Ilman nimeä se on vain lomake, ei maamerkki.

Natiivi HTML: <form aria-label>

Merkitsee liittyvien elementtien yleisen ryhmittelyn. Semanttisesti kevyempi kuin maamerkki — ruudunlukuohjelmat eivät mainosta ryhmiä maamerkki-valikossa. Käytetään <fieldset>+<legend> ryhmiteltyihin lomakeohjauselementteihin; turvaudu role="group"-rooliin muille kuin lomakeryhmittelyille.

Natiivi HTML: <fieldset>

Merkitsee elementin otsikoksi. Käytä ensin <h1>–<h6>-elementtejä — ne sisältävät oikean semantiikan ja tason automaattisesti. Turvaudu role="heading"-attribuuttiin vain, kun täytyy päivittää elementti, joka ei voi olla <h*>.

Natiivi HTML: <h1> – <h6>

Merkitsee elementin hyperlinkiksi — ohjauselementti, joka siirtyy uuteen resurssiin aktivoitaessa. Käytä ensin nativia HTML-elementtiä <a href>; turvaudu role="link"-attribuuttiin <span>- tai <div>-elementissä vain, kun natiivi elementti on mahdoton.

Natiivi HTML: <a href>

Merkitsee elementin luetteloksi. Käytä ensisijaisesti <ul>-, <ol>- tai <dl>-elementtiä — natiivielementti hoitaa roolin, laskurin ja visuaalisen merkinnän. Käytä role="list" vain, jos CSS:n list-style: none laukaisee Safarin listaroolinpoistoheuristiikan.

Natiivi HTML: <ul> / <ol>

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.

Natiivi HTML: <select> (single-select)

Merkitsee elementin yhdeksi kohdaksi luettelossa. Käytä <li>-elementtiä <ul>- tai <ol>-elementin sisällä — natiivielementti kantaa roolin ja sijainnin sarjassa. Käytä role="listitem" vain yhdistettynä eksplisiittiseen role="list":iin ei-lista-vanhemmalla.

Natiivi HTML: <li>

Sivun pääsisältömaamerkki — ensisijainen sisältö ilman toistuvia ylätunnisteita, navigointia ja alatunnisteita. <main>-elementti kantaa tämän roolin automaattisesti. Täsmälleen yksi main per sivu.

Natiivi HTML: <main>

Merkitsee säilön sovellusvalikoksi — Tiedosto/Muokkaa-tyylisten ponnahdusvalikkojen tai kontekstivalikoiden käyttöön. HTML-vastinetta ei ole. Sivuston navigaatiolista EI ole valikko; käytä <nav>-elementtiä, jonka sisällä on <ul> linkkejä.

Merkitsee säilön pysyväksi valikkoriviksi — aina näkyvissä olevaksi vaakasuoraksi Tiedosto/Muokkaa/Näytä-tyylisten valikkojen nauhaksi, jollainen löytyy työpöytäsovelluksista. Eroaa menu-roolista, joka on ponnahdusvalikko. Harvoin oikea malli verkossa.

Merkitsee elementin toiminnalliseksi kohteeksi valikon tai valikkonauhan sisällä. HTML-vastinetta ei ole — valikot ovat ARIA-exklusiivinen rakenne. Käytä tätä roolia vain rakentaessasi oikeaa valikkoa (sovellustyylinen); tavallinen navigaatiolista EI saa käyttää menu/menuitem-rakenteita.

Maamerkkirooli, joka ryhmittelee navigointilinkkejä — päänavigaatio, murupolku, sisällysluettelo. <nav>-elementti saa tämän roolin automaattisesti. Useita nav-elementtejä per sivu on tavallista, mutta jokaisella on oltava yksilöllinen saavutettava nimi.

Natiivi HTML: <nav>

Merkitsee elementin valittavaksi kohteeksi listboxin sisällä. Option TÄYTYY olla listboxin jälkeläinen (suoraan tai aria-owns-attribuutin kautta). Käytä natiivia <option>-elementtiä <select>-elementin sisällä; käytä role="option" vain rakentaessasi mukautettua listboxia tai combobox-ponnahdusikkunaa.

Natiivi HTML: <option>

Merkitsee elementin edistymisindikaattoriksi. Käytä ensin <progress>-elementtiä — se tarjoaa semantiikan, määritetyn visuaalin ja arvoattribuutit natiivisti. Käytä role="progressbar" vain kun natiivin elementtiin ei pysty tyylittelemään riittävästi.

Natiivi HTML: <progress>

Merkitsee elementin yksittäiseksi valinnaksi toisiaan poissulkevassa ryhmässä. Radion täytyy sijaita radiogroup-ryhmässä (tai natiivissa fieldset-elementissä). Käytä ensin <input type="radio">; käytä role="radio" vain kun natiivi syöte on mahdoton.

Natiivi HTML: <input type="radio">

Yleinen kiintopiste sisällölle, joka ei sovi banner-, main-, navigation-, complementary- tai contentinfo-rooleihin, mutta on silti riittävän tärkeä navigoitavaksi. <section>-elementistä tulee region-kiintopiste vain silloin, kun sillä on saavutettava nimi.

Natiivi HTML: <section aria-label>

Kiintopiste, joka ryhmittää hakolomakkeen. Mahdollistaa ruudunlukuohjelman käyttäjille suoran siirtymisen sivuston hakuun. Natiivi <search>-elementti (HTML 2024) kantaa tämän roolin automaattisesti; käytä role="search" <form>-elementissä laajemman selaintuen saamiseksi.

Natiivi HTML: <search>

Merkitsee elementin hakutehtävään tarkoitetuksi tekstisyötteeksi. Käytä ensin <input type="search"> — se tarjoaa tyhjennys-affordanssin useimmissa selaimissa ja hakusemantii­kan ilmaiseksi. Ota role="searchbox" käyttöön vain mukautetussa contenteditable-hakukentässä.

Natiivi HTML: <input type="search">

Merkitsee elementin sisältöosioiden tai yhdistelmäwidgetin kohteiden väliseksi erottimeksi. Käytä ensin <hr>:ää tekstikappaleiden temaattisiin katkoksiin; ota role="separator" käyttöön erottaessasi kohteita valikon, työkalupalkin tai muun widgetin sisällä.

Natiivi HTML: <hr>

Merkitsee elementin liukukontrolliksi, joka valitsee arvon vaihteluväliltä. Käytä ensin <input type="range">; turvaudu role="slider"-rooliin vain mukautetuissa tilanteissa — esimerkiksi kaksinapainen aluevalitsin, jota natiivielementti ei tue.

Natiivi HTML: <input type="range">

Reaaliaikainen alue ei-kiireellisille tiedotteille. Ruudunlukuohjelmat ilmoittavat muutokset kohteliaasti — seuraavalla tauolla, keskeyttämättä puhetta. Käytä rutiininomaisten vahvistusten, tulosmäärien ja edistymispäivitysten välittämiseen. Natiivi <output>-elementti kantaa tätä roolia.

Natiivi HTML: <output>

Merkitsee elementin on/off-kytkimeksi. Toiminnallisesti lähellä valintaruutua, mutta ilmoitetaan muodossa "kytkin, päällä" tai "kytkin, pois" eikä "valittu" — sopii paremmin asetuskytkimeen. Natiivista HTML:stä ei löydy vastaavaa elementtiä.

Merkitsee elementin yhdeksi välilehdeksi välilehtirajapinnassa. Välilehden TÄYTYY sijaita tablist-elementissä, ja sen PITÄISI viitata liittyvään tabpanel-elementtiin aria-controls-attribuutilla. Natiivista HTML:stä ei löydy välilehtielementtiä — välilehdet ovat pelkästään ARIA-kuvio.

Merkitsee säilön välilehtien nauhaksi välilehtirajapinnassa. Pitää sisällään role="tab"-lapset. Välilehdet ja tabpanel-elementit ovat pelkästään ARIA-kuvio — natiivista HTML:stä ei löydy tablist-elementtiä.

Merkitsee välilehteen paritetun sisältöpaneelin. Jokainen tabpanel on nimetty välilehdellään aria-labelledby-attribuutin kautta; välilehti viittaa paneeliin aria-controls-attribuutilla. Näytä yksi paneeli kerralla; piilota muut hidden-attribuutilla.

Merkitsee elementin yksi- tai monirivipohjaisksi tekstisyöttökentäksi. Käytä ensin <input type="text"> tai <textarea> — ne hoitavat kaiken tekstikenttäkäytöksen ilmaiseksi. Turvaudu role="textbox"-rooliin vain kun rakennat rich-text-editoria contenteditable-elementille.

Natiivi HTML: <input type="text"> / <textarea>

Merkitsee säilön työkalupalkiksi — ryhmäksi toisiinsa liittyviä ohjaimia (muotoilupalkki, kuvakepainikkeiden rivi). Vähentää sarkaintasausten määrää: kymmenen painikkeen työkalupalkista tulee yksi sarkainpysähdys, nuolinäppäimillä liikutaan välillä.

Merkitsee elementin hierarkkiseksi treeitem-kohteiden säilöksi — tiedostoselain, sisäkkäiset kategoriat tai organisaatiokaavio. Yksi sarkainpysähdys, nuolinäppäinnavigointi, laajennus ja kutistus. Natiiveja HTML-vastineita ei ole.

Merkitsee elementin yhdeksi kohteeksi puun sisällä. Treeitem voi olla laajennettava (lisää treeitem-kohteiden vanhempi) tai päätteinen (lehti). Käytä vain rakennettaessa hierarkkista selainta — tiedostoselain, organisaatiokaavio, sisäkkäiset kategoriat — joka tarvitsee yhden sarkainpysähdyksen nuolinäppäinnavigoinnin.

Määrittää, ilmoittaako avustava teknologia reaaliaikaisen alueen koko sisällön päivityksen yhteydessä vai vain muuttuneen osan. Oletusarvo on "false" (vain muutos). Aseta "true", kun asiayhteys on ymmärrettävissä vain kokonaisena lauseena.

Merkitsee alueen päivittyvän, jolloin avustava teknologia jättää väliaikaiset ilmoitukset väliin. Aseta arvoksi "true" latauksen tai suurten DOM-muutosten ajaksi; vaihda takaisin "false"-arvoon, kun alue on vakaa.

Ilmaisee valintaruudun, radiopainikkeen tai valikkokohteen nykyisen valitun tilan. Hyväksyy arvot "true", "false" tai "mixed". Natiivi HTML-valintaruutu hallitsee tätä automaattisesti — aseta se manuaalisesti vain mukautetuissa widgeteissä.

Merkitsee elementin, joka edustaa nykyistä kohdetta joukossa — aktiivisen sivun navigaatiossa, nykyisen vaiheen ohjatoiminnossa, tänään päivävalitsimessa. Tarkempi kuin aria-selected; käytä linkeissä ja kohteissa, joihin valinta ei sovi metaforana.

Ilmaisee, että ohjauselementti on havaittavissa ja tarkennettavissa mutta ei reagoi käyttäjän syötteeseen. Suosi natiivista HTML:n disabled-attribuuttia, kun se on käytettävissä; turvaudu aria-disabled-attribuuttiin, kun elementin on pysyttävä tarkennettavana tai näytettävä tooltip.

Ilmaisee, onko tiivistetty elementti — paljastauspainike, yhdistelmälaatikko, valikko, puunimike — tällä hetkellä auki. Arvot "true" tai "false". Yhdistetään yleensä aria-controls-attribuuttiin, joka osoittaa ohjauselementin avaamaan alueeseen.

Poistaa elementin ja kaikki sen jälkeläiset saavutettavuuspuusta. Näkevät käyttäjät näkevät elementin edelleen; avustava teknologia ei koskaan tavoita sitä. Varaa koristeelliselle sisällölle; älä koskaan sovella kohdistettavaan ohjauselementtiin.

Ilmaisee, että lomakeohjauselementti on epäonnistunut validoinnissa. Yhdistä aria-describedby-attribuuttiin, joka osoittaa ihmisluettavaan virheilmoitukseen, jotta ruudunlukuohjelma ilmoittaa sekä virheellisen tilan että syyn.

Merkitsee alueen, jonka päivitykset avustavan teknologian tulee ilmoittaa siirtämättä kohdistusta. Valitse "polite" lähes aina, "assertive" vain aidosti kiireellisiin päivityksiin. Alueen on oltava DOM:ssa sivun alkurenderöinnistä lähtien.

Kertoo avustavalle teknologialle, että muu sivu on poissa käytöstä dialogin ollessa auki. Aseta "true" role="dialog"- tai role="alertdialog"-elementille. Ei tee taustasta oikeasti inertti — yhdistä inert-attribuuttiin tai kohdistuslukitukseen.

Ilmaisee, onko vaihtopainike tällä hetkellä painettuna. Aseta "true" vaihdon ollessa päällä ja "false" sen ollessa pois; avustava teknologia ilmoittaa tilan yhdessä otsikon kanssa.

Ilmaisee, että lomakekentän arvoa ei voi muokata, mutta kenttä on silti käytettävissä — siihen voi siirtää kohdistuksen, kopioida sen sisällön ja se lähetetään lomakkeen mukana. Eroaa aria-disabled-tilasta, joka tekee kentästä kokonaan käyttökelvottoman.

Ilmaisee, että kohde yksi- tai monivalintasäilössä on tällä hetkellä valittuna. Käytetään tab-, option-, gridcell-, treeitem- ja vastaavissa rooleissa. Eroaa aria-checked- (valintaruutu/radio) ja aria-pressed- (vaihtopainike) -tiloista.

Komposiittisäätimessä osoittaa tällä hetkellä aktiivisen jälkeläisen ID:n. DOM-kohdistus pysyy säiliöllä, kun virtuaalinen kohdistus liikkuu lasten välillä. Vaihtoehto kiertävälle tabindex-mallille listboksissa, komboboxissa ja grideissä.

Tekstikentässä tai komboboxissa ilmaisee, millaista automaattista täydennystä säädin tarjoaa — sisäisiä ehdotuksia, vaihtoehtolistaa, molempia tai ei mitään. Eroaa HTML:n autocomplete-attribuutista, joka koskee lomakekentän selainsemantiikkaa.

Nimeää elementin tai elementit, joiden olemassaoloa tai sisältöä tämä ohjauselementti hallitsee. Yleisiä pareja: välilehti hallitsee välilehtipaneelia, paljastuspainike hallitsee paljastettua aluetta. Tuki avustavissa teknologioissa on epätasainen — käytä harkiten.

Viittaa yhden tai useamman elementin ID:hen, joiden teksti muodostaa elementin laajennetun kuvauksen. Luetaan saavutettavan nimen jälkeen. Käytetään ohjeteksteissä, muotovihjeinä ja lomakevirheissä.

Kertoo avustavalle teknologialle, että ohjauselementti avaa ponnahdusikkunan, ja minkä tyyppisen. Hyväksyy arvot "menu", "listbox", "tree", "grid", "dialog" tai "true" / "false". Käytä yhdessä aria-expanded-attribuutin kanssa, jotta AT voi myös ilmoittaa ponnahdusikkunan tilan.

Tarjoaa saavutettavan nimen merkkijonona, kun näkyvää tekstiä ei ole saatavilla. Käytä vain, kun näytöllä ei ole selitettä — jos näkyvä teksti on olemassa, suosi aria-labelledby-attribuuttia, jotta puhuttu nimi vastaa näkyvää.

Viittaa yhteen tai useampaan elementti-ID:hen, joiden näkyvä teksti muodostaa tämän elementin saavutettavan nimen. Suositellaan aria-label-attribuutin sijaan, kun näytöllä oleva teksti jo kuvaa ohjauselementin.

Ilmaisee elementin hierarkkisen tason rakenteen sisällä. Pakollinen role="heading"-elementeissä; käytetään myös role="treeitem"- ja role="listitem"-elementeissä sisäkkäisissä listoissa. Kokonaislukuarvo, alkaen luvusta 1.

Ilmaisee vanhempi-lapsi-suhteen saavutettavuuspuussa, kun DOM-rakenne ei sitä ilmaise. Uudelleensijoittaa viitatut elementit tämän elementin lapsiksi avustavaa teknologiaa varten. Tehokas työkalu — helppo väärinkäyttää.

Kohteen sijainti joukossa, kun DOM ei pysty sitä ilmaisemaan — tyypillisesti siksi, että kohteet ovat virtualisoituja, sivutettuja tai suodatettuja. Yhdistä aina aria-setsize-attribuuttiin, jotta ruudunlukuohjelmat voivat ilmoittaa "3 / 47".

Ilmaisee, että käyttäjän on täytettävä kenttä ennen lomakkeen lähettämistä. Käytä HTML:n required-attribuuttia natiiveissa lomakekentissä; ota aria-required käyttöön vain, kun HTML-vastinetta ei ole — esim. divistä rakennetussa comboboxissa.

Joukon kohteiden kokonaismäärä, kun DOM ei sisällä niitä kaikkia. Yhdistetään aria-posinset-attribuuttiin, jotta ruudunlukuohjelma voi ilmoittaa "kohde 14 / 5 000" vaikka vain viisi olisi renderöity. Käytä arvoa -1, jos kokonaismäärä on tuntematon.

Sarake- tai riviylätunnisteessa lajiteltavassa ruudukossa tai taulukossa: ilmoittaa nykyisen lajittelusuunnan. Arvot: "ascending", "descending", "other" tai "none". Vain yhdellä ylätunnisteella kerrallaan saa olla lajiteltu arvo.

Aluewidgetin nykyinen numeerinen arvo — liukusäädin, edistymispalkki, pyöristyspainike, vierityspalkki. Yhdistä aria-valuemin- ja aria-valuemax-arvoihin, jotta avustava teknologia voi ilmoittaa merkityksellisen sijainnin. Käytä aria-valuetext-ominaisuutta ei-numeerisille nimikkeille.