Standardy · ARIA

Stan Stan widgetu

aria-modal

Informuje technologie wspomagające, że reszta strony jest nieaktywna podczas otwarcia okna dialogowego. Ustaw na „true" dla role="dialog" lub role="alertdialog". Nie czyni tła faktycznie nieaktywnym — połącz z atrybutem inert lub pułapką fokusu.

Kiedy stosować

Na elemencie role="dialog" lub role="alertdialog", który powinien blokować interakcję z resztą strony podczas swojego otwarcia. Ustaw aria-modal="true", aby czytnik ekranu ograniczył wirtualny kursor do okna dialogowego i ogłosił treści w tle jako niedostępne.

Modalne okno dialogowe ma trzy obowiązki:

  1. aria-modal="true" — informuje technologię wspomagającą, że okno jest modalne.
  2. Tło nieaktywne — stosowane przez atrybut inert na otaczającej treści lub przez zarządzanie pułapką fokusu przez JavaScript. Bez tego użytkownicy klawiatury mogą wytabulować się z okna dialogowego.
  3. Fokus inicjalny — przenosi fokus do okna dialogowego po jego otwarciu i przywraca fokus na wyzwalaczu po zamknięciu.

Sam aria-modal obsługuje stronę czytnika ekranu; nie zatrzymuje użytkownika klawiatury przed wytabulowaniem się poza okno dialogowe. Obsługa przeglądarek dla wnioskowania o nieaktywności na podstawie aria-modal jest niespójna, więc zawsze łącz oba podejścia.

Natywny element HTML <dialog> z .showModal() obsługuje wszystkie trzy wymagania automatycznie. Preferuj go tam, gdzie jest to możliwe.

Jak utrzymywać synchronizację

Prawidłowe wartości to "true" i "false". Renderuj "true" gdy okno dialogowe jest otwarte; usuń atrybut lub ustaw "false" gdy jest zamknięte (zazwyczaj zamknięte okno nie istnieje w DOM, więc atrybut nie ma znaczenia).

aria-modal jest łączony z dwoma atrybutami etykietowania:

  • aria-labelledby="<id-tytułu-okna>" — wskazuje na widoczny nagłówek.
  • aria-describedby="<id-treści-okna>" — opcjonalny, dla krótkiego opisu.

Razem dają czytnikowi ekranu spójne ogłoszenie otwarcia: „Okno dialogowe, Usuń konto?, Tej operacji nie można cofnąć.”

Częste błędy

  • aria-modal="true" bez pułapki fokusu — użytkownicy klawiatury tabulują w tło.
  • Używanie aria-modal na niemodalnym popoverze lub podpowiedzi. Używaj role="dialog" tylko dla prawdziwych modalnych okien dialogowych; popover nie jest oknem dialogowym.
  • Brak aria-labelledby — czytnik ekranu ogłasza „Okno dialogowe” bez nazwy.
  • Brak przeniesienia fokusu do okna dialogowego po jego otwarciu.
  • Brak przywrócenia fokusu na oryginalnym wyzwalaczu po zamknięciu.
  • Oznaczanie tła przez aria-hidden="true" zamiast inert — fokus klawiatury nadal ucieka; ograniczony jest tylko kursor wirtualny czytnika ekranu.
  • Dwa jednocześnie otwarte okna modalne z aria-modal="true". Drzewo dostępności ulega dezorientacji; pokazuj jedno na raz.

Przykład

<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="confirm-title"
  aria-describedby="confirm-body"
>
  <h2 id="confirm-title">Usunąć konto?</h2>
  <p id="confirm-body">Tej operacji nie można cofnąć.</p>

  <button type="button" autofocus>Anuluj</button>
  <button type="button">Usuń</button>
</div>