aria-posinset

Kiedy używać

Stosuj, gdy DOM nie zawiera pełnego zbioru — wirtualizowane listy renderujące tylko widoczne pozycje, stronicowane siatki, filtrowane combobox, kanały z nieskończonym przewijaniem. Bez aria-posinset i aria-setsize czytnik ekranu musi zgadywać na podstawie liczby rodzeństwa i ogłosi „element 1 z 10”, gdy użytkownik jest w rzeczywistości na elemencie 327 z 5 000.

Atrybut jest prawidłowy na elementach wewnątrz kontenerów z natury zbiorowych: option w listbox, menuitem w menu, treeitem w tree, tab w tablist, article w feed, row w grid.

Jeśli DOM naturalnie zawiera wszystkie elementy w kolejności źródłowej, aria-posinset nie jest potrzebny — technologia wspomagająca sama zlicza rodzeństwo.

Jak działa

Wartość to dodatnia liczba całkowita — 1-bazowy indeks tego elementu w pełnym zbiorze. Łącz z aria-setsize na tym samym elemencie; oba atrybuty należą do elementów, nie do kontenera.

Gdy elementy są filtrowane, aktualizuj oba atrybuty, aby odzwierciedlały widoczny i istotny zbiór, a nie oryginalną pełną listę. W przeciwnym razie użytkownicy słyszą pozycje niezgodne z tym, po czym mogą nawigować.

aria-setsize="-1" jest prawidłowy dla przypadków, gdy łączna liczba jest naprawdę nieznana (otwarty kanał z wyszukiwaniem w trakcie pisania). Niektóre technologie wspomagające ogłaszają to jako „wiele”; inne milczą.

Typowe błędy

• Ustawienie aria-posinset bez aria-setsize. Brakuje połowy informacji; technologia wspomagająca nie może powiedzieć „3 z ilu”.
• Zapomnienie o aktualizacji wartości po sortowaniu lub filtrowaniu. Użytkownicy słyszą nieaktualne pozycje.
• Umieszczanie atrybutów na kontenerze zamiast na elementach.
• Używanie aria-posinset, gdy DOM już odzwierciedla pełny zbiór — technologia wspomagająca i tak liczyłaby poprawnie, a teraz masz dwa źródła prawdy, które mogą się rozejść.
• Zerowe lub ujemne wartości dla aria-posinset (wartości ujemne są niedozwolone; tylko aria-setsize przyjmuje -1).
• Numery pozycji niezgodne z porządkiem wizualnym — użytkownik czytnika ekranu słyszy „element 5”, gdy podświetlony jest trzeci widoczny element.

Przykład

<!-- Wirtualizowany listbox: w DOM są tylko elementy 12–16, a zbiór liczy 5 000 pozycji -->
<div role="listbox" aria-label="Klienci">
  <div role="option" aria-posinset="12" aria-setsize="5000">Klient 12</div>
  <div role="option" aria-posinset="13" aria-setsize="5000">Klient 13</div>
  <div role="option" aria-posinset="14" aria-setsize="5000" aria-selected="true">Klient 14</div>
  <div role="option" aria-posinset="15" aria-setsize="5000">Klient 15</div>
  <div role="option" aria-posinset="16" aria-setsize="5000">Klient 16</div>
</div>