Właściwość Stan widgetu

`aria-valuenow`

Bieżąca wartość liczbowa widżetu zakresu — suwaka, paska postępu, spinbuttona, paska przewijania. Łącz z aria-valuemin i aria-valuemax, aby technologie asystujące mogły ogłosić znaczącą pozycję. Dla etykiet nienumerycznych stosuj aria-valuetext.

Kiedy stosować

Na każdym własnym widżecie reprezentującym wartość w zakresie: role="slider", role="progressbar", role="spinbutton", role="scrollbar". Atrybut przechowuje bieżącą wartość liczbową. Prawie zawsze łączy się go z aria-valuemin i aria-valuemax, które wspólnie pozwalają technologii asystującej wyliczyć i ogłosić procent oraz wartość bezwzględną.

Zazwyczaj nie jest potrzebny przy natywnym <input type="range"> ani <progress> — przeglądarka udostępnia wartość automatycznie. Po aria-valuenow sięgaj, gdy widżet zbudowany jest z własnego znacznika.

Jak działa

Wartość jest liczbą (całkowitą lub zmiennoprzecinkową). Technologia asystująca ogłasza ją jako bieżącą pozycję widżetu, często razem z procentem przedziału min–max: „Głośność, suwak, 7 z 10, 70 procent.”

Jeśli wartość widżetu jest bardziej znacząca jako etykieta niż jako liczba — „Piątek” na suwaiku wyboru dnia, „Średni” na selektorze trójstopniowym — podaj aria-valuetext z czytelną etykietą. Technologia asystująca odczyta aria-valuetext zamiast aria-valuenow, przy czym oprogramowanie ignorujące valuetext nadal ma numeryczny fallback. Zawsze ustawiaj oba atrybuty jednocześnie.

Dla progressbar możesz pominąć aria-valuenow przy nieokreślonym postępie (przypadek spinnera). Dla slider atrybut jest wymagany.

Częste błędy

Ustawienie aria-valuenow bez aria-valuemin i aria-valuemax. Technologia asystująca nie zna zakresu i ogłasza samą liczbę bez kontekstu.
Aktualizowanie pozycji wizualnej przez transformacje CSS bez aktualizowania aria-valuenow. Użytkownicy czytników ekranu słyszą zawsze wartość początkową.
Wartość poza zakresem min/max — aria-valuenow="150" gdy max wynosi 100. Technologia asystująca albo obcina wartość, albo ogłasza ją dosłownie; w obu przypadkach to błąd.
Pominięcie aria-valuetext dla skal nienumerycznych. Użytkownicy słyszą „3 z 5”, gdy skala to w rzeczywistości „Niski / Średnio-niski / Średni / Średnio-wysoki / Wysoki”.
Użycie aria-valuenow na czymś, co nie jest widżetem zakresu — zwykłym przycisku, ikonie. Atrybut nie ma żadnego efektu poza obsługiwanymi rolami.
Brak synchronizacji modelu klawiaturowego. Widżet musi reagować na strzałki, Home, End, Page Up, Page Down — sam atrybut nie zapewnia obsługi klawiatury.

Przykład

<div
  role="slider"
  tabindex="0"
  aria-label="Volume"
  aria-valuemin="0"
  aria-valuemax="10"
  aria-valuenow="7"
  aria-valuetext="7 out of 10"
>
  <div class="slider-thumb" style="left: 70%"></div>
</div>