Strony internetowe i programowanie

Jak tworzyć dostępne okna dialogowe modalne z HTML, CSS i JavaScript

How to Create Accessible Modal Dialogs with HTML, CSS, and JavaScript

Buduj dostępne okna dialogowe modalne, korzystając z natywnego elementu dialog HTML. Dowiedz się, jak otwierać i zamykać wyskakujące okna, zarządzać fokusowaniem klawiatury, stylizować tła oraz tworzyć okna dialogowe potwierdzające bez biblioteki JavaScript.

Jak tworzyć dostępne okna modalne za pomocą HTML, CSS i JavaScript

Odwiedzający klika przycisk w Twojej witrynie. Pojawia się wyskakujące okno z formularzem, komunikatem potwierdzenia lub dodatkowymi informacjami.

Stworzenie wizualnego wyskakującego okna jest łatwe. Zapewnienie jego poprawnego działania z klawiaturą, czytnikiem ekranu i przeglądarką mobilną to zupełnie inna sprawa.

Wiele niestandardowych implementacji okien modalnych opiera się na dużej ilości JavaScriptu do zarządzania fokusem, blokowania interakcji ze stroną i obsługi klawisza Escape.

Nowoczesny HTML oferuje prostsze podejście: natywny element <dialog>.

Zapewnia on wiele zachowań oczekiwanych od okna modalnego bezpośrednio w przeglądarce. Możesz utworzyć funkcjonalne wyskakujące okno za pomocą niewielkiej ilości HTML, CSS i JavaScriptu, bez instalowania frameworka ani wtyczki.

W tym samouczku zbudujemy wielokrotnego użytku okno modalne, ostylujemy je, dodamy okno potwierdzenia i omówimy szczegóły dostępności istotne w rzeczywistych witrynach.

1. Czym okno modalne różni się od zwykłego wyskakującego okna?

Okno modalne tymczasowo wymaga od odwiedzającego interakcji z określoną częścią interfejsu przed powrotem do głównej strony.

Typowe przykłady obejmują:

  • Potwierdzenie usunięcia elementu.
  • Wyświetlenie formularza kontaktowego.
  • Poproszenie o potwierdzenie przed opuszczeniem strony.
  • Pokazanie dodatkowych informacji o produkcie.
  • Edytowanie ustawienia aplikacji.

Prawidłowo zaimplementowane okno modalne powinno jasno określać swój cel, oferować oczywisty sposób zamknięcia i odpowiednio zarządzać fokusem klawiatury.

Natywny element <dialog> obsługuje zarówno zachowanie modalne, jak i niemodalne.

Metoda Zachowanie
showModal() Otwiera okno modalne i czyni resztę dokumentu nieaktywną
show() Otwiera okno niemodalne
close() Zamyka okno
method="dialog" Pozwala przyciskowi formularza zamknąć okno

Zachowanie modalne obejmuje zarządzanie fokusem i obsługę klawiatury zapewniane przez przeglądarkę.

2. Utwórz pierwsze okno modalne w HTML

Zacznijmy od prostego przykładu: przycisku, który otwiera okno zawierające tytuł, tekst i przycisk zamykania.

```html
<button type="button" id="openDialog">
    View delivery information
</button>

<dialog id="deliveryDialog"
        aria-labelledby="deliveryTitle">

    <h2 id="deliveryTitle">
        Delivery information
    </h2>

    <p>
        Orders are prepared within two business days.
        You will receive a tracking link by email.
    </p>

    <form method="dialog">
        <button type="submit" autofocus>
            Close
        </button>
    </form>

</dialog>

<script>
const openButton = document.getElementById('openDialog');
const dialog = document.getElementById('deliveryDialog');

openButton.addEventListener('click', () => {
    dialog.showModal();
});
</script>

To wystarczy, aby utworzyć działające okno modalne.

Gdy odwiedzający kliknie przycisk, `showModal()` otwiera okno nad zawartością strony.

Przeglądarka automatycznie obsługuje kilka ważnych zachowań:

- Okno trafia do górnej warstwy, ponad zwykłą zawartością strony.
- Reszta dokumentu staje się nieaktywna.
- Fokus klawiatury przenosi się do okna.
- Naciśnięcie Escape zwykle je zamyka.
- Fokus zwykle wraca do przycisku otwierającego po zamknięciu okna.

Przycisk zamykania używa `method="dialog"`, więc nie wymaga procedury obsługi zdarzenia JavaScript.

## 3. Ostyluj okno za pomocą CSS

Domyślne okno działa, ale jego wygląd jest podstawowy.

Możemy nadać mu zaokrąglone rogi, wygodne odstępy, responsywną szerokość i tło.
dialog {
    width: min(90vw, 520px);
    max-height: 85vh;
    box-sizing: border-box;
    padding: 2rem;
    border: 0;
    border-radius: 14px;
    background: #fff;
    color: #20242b;
    box-shadow: 0 20px 70px rgba(0, 0, 0, .2);
    overflow: auto;
}

dialog::backdrop {
    background: rgba(15, 23, 42, .65);
    backdrop-filter: blur(3px);
}

dialog h2 {
    margin-top: 0;
    font-size: 1.5rem;
}

dialog p {
    line-height: 1.6;
}

dialog button {
    padding: .75rem 1.25rem;
    border: 0;
    border-radius: 8px;
    background: #2458d3;
    color: #fff;
    font: inherit;
    cursor: pointer;
}

dialog button:focus-visible {
    outline: 3px solid #f59e0b;
    outline-offset: 3px;
}

Pseudo-element `::backdrop` stylizuje warstwę za oknem modalnym.

Pojawia się tylko wtedy, gdy okno jest wyświetlane modalnie, na przykład przez `showModal()`.

Okno otwarte za pomocą `show()` nie otrzymuje automatycznie tego samego zachowania tła modalnego.

### Dlaczego używać górnej warstwy?

Tradycyjne niestandardowe wyskakujące okna często opierają się na coraz większych wartościach `z-index`.

Okno modalne otwarte za pomocą `showModal()` trafia do górnej warstwy przeglądarki, co pozwala uniknąć wielu problemów z kontekstem stosu.

Jest to szczególnie pomocne w witrynach zawierających przyklejone nagłówki, pływające widżety i złożone kreatory stron.

## 4. Zrozum dostępność klawiaturową

Okno modalne musi działać bez myszy.

Wyobraź sobie odwiedzającego, który porusza się po Twojej witrynie za pomocą klawisza Tab. Gdy okno modalne się otworzy, powinien móc wchodzić w interakcję z jego kontrolkami, nie przechodząc przypadkowo do strony za nim.

Natywne okno modalne pomaga w tym zachowaniu.

W3C opisuje element dialog HTML jako technikę tworzenia dostępnych okien modalnych, obejmującą zatrzymywanie fokusu i przywracanie fokusu po zamknięciu okna.

### Nadaj oknu dostępną nazwę

Użyj widocznego nagłówka i odwołaj się do niego za pomocą `aria-labelledby`:
<dialog aria-labelledby="settingsTitle">
    <h2 id="settingsTitle">Account settings</h2>
    ...
</dialog>

Daje to technologiom wspomagającym znaczącą nazwę okna.

### Starannie wybierz początkowy fokus

Atrybut `autofocus` może wskazać kontrolkę, która powinna otrzymać fokus po otwarciu okna modalnego.

W przypadku okna informacyjnego odpowiednie może być ustawienie fokusu na przycisku zamykania.


Illustration of the article's main concept



W przypadku formularza większy sens może mieć ustawienie fokusu na pierwszym polu.

W przypadku potwierdzenia destrukcyjnej operacji często lepiej ustawić fokus na bezpieczniejszej akcji, takiej jak Anuluj.

Unikaj umieszczania `tabindex` bezpośrednio na elemencie `<dialog>`; specyfikacja HTML zabrania tego atrybutu na samym elemencie.

### Zawsze zapewniaj widoczny przycisk zamykania

Chociaż Escape zwykle zamyka okno modalne, widoczna kontrolka zamykania pozostaje niezbędna.

Odwiedzający na urządzeniach mobilnych mogą nie mieć fizycznej klawiatury, a niektórzy użytkownicy nie wiedzą, że Escape może zamknąć wyskakujące okno.

## 5. Utwórz okno potwierdzenia z dwoma przyciskami

Zbudujmy teraz bardziej użyteczny przykład: potwierdzenie usunięcia zapisanego elementu.

Odwiedzający powinien móc wybrać Anuluj lub Usuń.

HTML zapewnia wygodny mechanizm poprzez `method="dialog"` i właściwość `returnValue` okna.
<button type="button" id="deleteItem">
    Delete item
</button>

<dialog id="confirmDialog"
        aria-labelledby="confirmTitle">

    <h2 id="confirmTitle">
        Delete this item?
    </h2>

    <p>
        This action cannot be undone.
    </p>

    <form method="dialog">
        <button value="cancel" autofocus>
            Cancel
        </button>

        <button value="confirm">
            Delete
        </button>
    </form>

</dialog>

<script>
const deleteButton = document.getElementById('deleteItem');
const confirmDialog = document.getElementById('confirmDialog');

deleteButton.addEventListener('click', () => {
    confirmDialog.returnValue = 'cancel';
    confirmDialog.showModal();
});

confirmDialog.addEventListener('close', () => {
    if (confirmDialog.returnValue === 'confirm') {
        // Call your application deletion logic here.
        console.log('Deletion confirmed');
    }
});
</script>

Ważnym szczegółem jest to, że kliknięcie przycisku wewnątrz formularza `method="dialog"` zamyka okno i ustawia jego `returnValue`.

Nasz kod sprawdza, czy użytkownik wybrał `confirm`.

Zresetowanie wartości przed otwarciem zapobiega pomyleniu wcześniejszego potwierdzenia z nowym, jeśli użytkownik zamknie okno za pomocą Escape.

Przykład celowo niczego nie usuwa. W rzeczywistej aplikacji potwierdzona akcja wywołałaby własny punkt końcowy PHP lub kontroler aplikacji, z niezbędną autoryzacją i ochroną CSRF.

## 6. Przetestuj przepływ potwierdzenia

Przydatną demonstracją jest lista zapisanych elementów, z których każdy ma przycisk Usuń. Kliknięcie Usuń powinno otworzyć okno potwierdzenia. Anuluj powinno pozostawić element bez zmian; Potwierdź powinno usunąć tylko wybrany element.

Ilustruje to przepływ potwierdzenia bez zmieniania rzeczywistych danych witryny.

## 7. Dodaj formularz kontaktowy wewnątrz okna

Formularz kontaktowy to kolejny częsty przypadek użycia.

Istnieje jednak ważna różnica między zamknięciem okna a przesłaniem danych do serwera.

Formularz z `method="dialog"` zamyka wyskakujące okno. Nie wysyła konwencjonalnego żądania HTTP do Twojego backendu PHP.

W przypadku rzeczywistego formularza kontaktowego użyj zwykłego przesłania formularza lub żądania AJAX.

Na przykład:
<dialog id="contactDialog"
        aria-labelledby="contactTitle">

    <h2 id="contactTitle">
        Contact us
    </h2>

    <form action="/contact-handler.php" method="post">
        <label for="contactEmail">
            Your email
        </label>

        <input
            type="email"
            id="contactEmail"
            name="email"
            required
            autocomplete="email"
            autofocus
        >

        <label for="contactMessage">
            Your message
        </label>

        <textarea
            id="contactMessage"
            name="message"
            required
        ></textarea>

        <button type="submit">
            Send message
        </button>

        <button type="button" id="closeContact">
            Cancel
        </button>
    </form>
</dialog>

Przycisk Wyślij przesyła formularz w standardowy sposób.

Przycisk Anuluj powinien zamknąć okno bez przesyłania:
document.getElementById('closeContact')
    .addEventListener('click', () => {
        document.getElementById('contactDialog').close();
    });

Twój handler PHP nadal musi weryfikować przesłane dane, wdrażać ochronę antyspamową i zwracać znaczącą odpowiedź sukcesu lub błędu.

Okno modalne poprawia interfejs; nie zastępuje bezpieczeństwa formularza po stronie serwera.

## 8. Czy użytkownicy mogą zamknąć okno, klikając poza nim?

Wiele witryn pozwala odwiedzającym zamknąć wyskakujące okno, klikając jego tło.

To zachowanie jest często nazywane *light dismiss*.

Nowoczesny HTML zawiera atrybut `closedby`, który może określać, czy okno można zamknąć poprzez interakcję zewnętrzną, żądania zamknięcia platformy lub jawne kontrolki.

Na przykład:
<dialog id="infoDialog" closedby="any">
    <h2>More information</h2>
    <p>Additional details appear here.</p>

    <form method="dialog">
        <button>Close</button>
    </form>
</dialog>

Wartość `closedby="any"` umożliwia zachowanie light dismiss w przeglądarkach, które je obsługują.

Należy jednak sprawdzić obsługę nowszych funkcji okna w docelowych przeglądarkach. Podstawowe interfejsy API `showModal()` i `close()` są szerzej ugruntowane.

W krytycznych oknach potwierdzenia przypadkowe zamknięcie przez kliknięcie poza oknem może być niepożądane.

We wszystkich przypadkach zachowaj widoczną kontrolkę zamykania lub anulowania.

## 9. Unikaj tych typowych błędów implementacji


Technical workflow illustration



### Otwieranie okna modalnego przez dodanie atrybutu `open`

Ten kod:
dialog.setAttribute('open', '');

nie zapewnia takiego samego zachowania jak:
dialog.showModal();

Atrybut `open` wyświetla okno w trybie niemodalnym. Nie czyni automatycznie reszty dokumentu nieaktywną.

Użyj `showModal()`, gdy potrzebujesz rzeczywistego okna modalnego.

### Usuwanie atrybutu open w celu zamknięcia okna modalnego

Unikaj ręcznego usuwania atrybutu `open` z aktywnego okna modalnego.

Użyj:
dialog.close();

Jest to zgodne z zamierzonym cyklem życia i zapewnia odpowiednie zachowanie przy zamykaniu.

### Używanie linku zamiast przycisku

Kontrolka, która otwiera działanie interfejsu, powinna zazwyczaj być przyciskiem:
<button type="button">Open settings</button>


Linków używaj do nawigacji do innego zasobu.

### Zapominanie o widoczności fokusu

Użytkownicy poruszający się za pomocą klawiatury potrzebują widocznego wskazania, która kontrolka jest aktywna.

Zachowaj wyraźny styl `:focus-visible`, zamiast usuwać obrys fokusu przeglądarki bez zamiennika.

### Umieszczanie okna wewnątrz ukrytego kontenera

Jeśli nadrzędny kontener jest ukryty lub jeśli CMS dynamicznie zastępuje otaczający znacznik, okno może działać nieoczekiwanie.

W integracjach z kreatorami stron preferuj stabilny kontener i upewnij się, że JavaScript uruchamia się po wstawieniu okna do dokumentu.

## 10. Zintegruj okno z WordPress lub Joomla

Nie musisz tworzyć rozszerzenia tylko po to, aby użyć natywnego elementu dialog.

W przypadku prostej witryny integracja składa się z trzech części:

| Część | Gdzie trafia |
|---|---|
| Znacznik HTML | Niestandardowy blok HTML, moduł, szablon lub element kreatora stron |
| CSS | Niestandardowy CSS motywu lub szablonu |
| JavaScript | Niestandardowy JavaScript motywu/szablonu lub obsługiwana funkcja wstrzykiwania kodu |

### WordPress

W WordPress możesz umieścić HTML w bloku Custom HTML, pod warunkiem że Twoje konto i konfiguracja edytora pozwalają na niezbędny znacznik.

Dodaj stylizację za pomocą obsługiwanego mechanizmu niestandardowego CSS motywu.

W przypadku JavaScript użyj obszaru skryptów obsługiwanego przez motyw, motywu potomnego lub renomowanego rozszerzenia do wstawiania kodu, które prawidłowo obsługuje JavaScript.

Niektóre edytory i konfiguracje bezpieczeństwa filtrują elementy `<script>`. Nie zakładaj, że JavaScript wklejony bezpośrednio do bloku treści zostanie wykonany.

### Joomla

W Joomla okno może zawierać niestandardowy moduł lub edytor, który pozwala na odpowiedni znacznik HTML.

Dodaj CSS do niestandardowego arkusza stylów szablonu, takiego jak `user.css` w witrynie opartej na Cassiopeia.

Umieść JavaScript w obsługiwanej lokalizacji niestandardowych skryptów szablonu lub za pomocą odpowiedniego rozszerzenia.

W zależności od skonfigurowanego edytora i filtrów tekstu Joomla może usuwać niektóre elementy lub atrybuty podczas zapisywania treści.

Jeśli Twój znacznik znika, sprawdź konfigurację edytora i filtrowania, zamiast wielokrotnie wklejać ten sam kod.

### Kreatory stron

Ta sama zasada dotyczy wizualnych kreatorów stron: korzystaj z ich możliwości integracji HTML, CSS i JavaScript.

W przypadku treści ładowanych dynamicznie inicjalizuj nasłuchiwacze zdarzeń dopiero po utworzeniu odpowiednich elementów.

Jeśli strona zawiera wiele okien, nadaj każdemu unikalny identyfikator.

## 11. Przetestuj okno modalne przed publikacją

Okno, które wygląda poprawnie na komputerze, może nadal mieć problemy z użytecznością.

Przetestuj je za pomocą myszy, klawiatury i urządzenia mobilnego.

| Test | Oczekiwany wynik |
|---|---|
| Kliknięcie przycisku otwierającego | Okno się pojawia |
| Naciśnięcie Tab | Fokus pozostaje w obrębie kontrolek okna modalnego |
| Naciśnięcie Shift + Tab | Odwrotna nawigacja klawiaturą działa |
| Naciśnięcie Escape | Okno zamyka się, gdy jest to dozwolone |
| Kliknięcie Zamknij lub Anuluj | Okno się zamyka |
| Zamknięcie okna | Fokus wraca we właściwe miejsce |
| Otwarcie na urządzeniu mobilnym | Treść pozostaje czytelna i można ją przewijać |
| Przesłanie nieprawidłowego formularza | Informacja zwrotna o walidacji jest widoczna |
| Przesłanie prawidłowego formularza | Aplikacja prawidłowo obsługuje dane |
| Użycie czytnika ekranu | Okno ma zrozumiałą nazwę |

Technika WCAG H102 W3C zawiera przydatne wskazówki dotyczące weryfikacji natywnego zachowania okna modalnego.

## 12. Kiedy używać okna dialogowego zamiast wtyczki?

Natywne okno doskonale nadaje się do małych, skupionych interakcji: potwierdzeń, paneli informacyjnych i prostych formularzy.

W przypadku bardziej złożonych potrzeb, takich jak kreatory wieloetapowe, zaawansowane galerie lub okna głęboko zintegrowane z przepływem pracy CMS, dedykowany komponent lub rozszerzenie może nadal być opcją łatwiejszą w utrzymaniu.

Zaletą podejścia natywnego jest to, że zapewnia solidną, wspieraną przez przeglądarkę podstawę bez wprowadzania kolejnej zależności JavaScript.

Zmniejsza również ilość niestandardowego zarządzania fokusem i klawiaturą, które musisz samodzielnie implementować.

## Wnioski: zacznij od wbudowanych możliwości przeglądarki

Okno modalne nie musi wymagać dużej biblioteki JavaScript.

Natywny element HTML `<dialog>` zapewnia skuteczną podstawę dla dostępnych wyskakujących okien, komunikatów potwierdzenia i formularzy.

Za pomocą `showModal()`, `close()`, `method="dialog"` i kilku reguł CSS możesz utworzyć interfejs działający w nowoczesnych przeglądarkach, korzystając z wbudowanego zarządzania fokusem i obsługi klawiatury.

W przypadku WordPress, Joomla i niestandardowych witryn PHP może to być wydajna alternatywa dla instalowania kolejnej wtyczki do stosunkowo prostej interakcji.

Kluczem jest prawidłowe korzystanie z natywnego zachowania, zapewnienie jasnych kontrolek i przetestowanie wyniku za pomocą rzeczywistych interakcji klawiaturą i urządzeniami mobilnymi.

## Oficjalne i techniczne odniesienia

- [MDN — element dialog HTML](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog)
- [W3C — Tworzenie okien modalnych za pomocą HTML dialog](https://www.w3.org/WAI/WCAG22/Techniques/html/H102)
- [WHATWG — specyfikacja HTML dialog](https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element)