treeitem

Kiedy stosować

Wewnątrz role="tree" — dla każdego widocznego węzła. Jeśli węzeł ma dzieci, ustaw aria-expanded="true" lub "false" i umieść (lub powiąż) role="group" zawierający podrzędne treeitemy. Jeśli węzeł jest liściem, całkowicie pomiń aria-expanded (NIE ustawiaj go na "false" — oznajmiałoby to „zwinięty”, mimo że nie ma nic do rozwinięcia).

Ustaw aria-level (głębokość liczona od 1), aria-posinset (pozycja wśród rodzeństwa, od 1) i aria-setsize (łączna liczba rodzeństwa) dla każdego treeitemu, gdy wizualne zagnieżdżenie nie wynika wprost ze struktury DOM.

Jeśli chodzi wyłącznie o „listę linków z zagnieżdżonymi podlinkami”, lepszym wyborem jest <nav> z zagnieżdżonymi <ul> i <a>. Widok drzewa stosuj tylko wtedy, gdy doświadczenie stanowi hierarchiczny przeglądacz z jednym punktem tabulacji.

Kontrakt klawiaturowy i fokus

Zgodnie z wzorcem APG treeview:

• Tab przenosi fokus do drzewa, na bieżący treeitem; kolejny Tab przenosi fokus poza drzewo.
• Strzałki góra/dół przesuwają fokus między widocznymi węzłami (pomijając zwinięte dzieci).
• Strzałka w prawo: jeśli węzeł jest zwinięty — rozwija go; jeśli rozwinięty — przenosi do pierwszego dziecka.
• Strzałka w lewo: jeśli węzeł jest rozwinięty — zwija go; jeśli zwinięty — przenosi do rodzica.
• Home / End przenosi do pierwszego / ostatniego widocznego węzła.
• Enter lub Spacja aktywuje (zaznacza) bieżący element.
• Podpowiadanie typem: wpisanie litery przenosi fokus do kolejnego pasującego widocznego węzła.

Częste błędy

• aria-expanded="false" na węźle-liściu — oznajmia fałszywy stan „zwinięty”.
• Każdy treeitem ma tabindex="0". Wzorzec zakłada jeden punkt tabulacji; tylko aktualnie sfokusowany element niesie tabindex="0".
• Strzałki prawo/lewo użyte do przechodzenia między rodzeństwem zamiast do rozwijania/zwijania.
• Podrzędne treeitemy umieszczone bezpośrednio w rodzicielskim <li> bez opakowującego role="group". Czytniki ekranu nie mogą wtedy ogłosić grupy jako całości.
• Brak aria-level przy płaskim DOM (np. gdy drzewo renderowane jest z pozycjonowaniem absolutnym).

Przykład

<ul role="tree" aria-label="Files">
  <li role="treeitem" aria-expanded="true" tabindex="0">
    Documents
    <ul role="group">
      <li role="treeitem" tabindex="-1">Resume.pdf</li>
      <li role="treeitem" aria-expanded="false" tabindex="-1">
        Photos
        <ul role="group">
          <li role="treeitem" tabindex="-1">2025-summer.jpg</li>
        </ul>
      </li>
    </ul>
  </li>
  <li role="treeitem" tabindex="-1">Downloads</li>
</ul>