reportValidity i setCustomValidity

Constraint Validation API udostępnia dwie metody sterujące wbudowanym interfejsem walidacji przeglądarki: reportValidity (wyświetla podpowiedź) oraz setCustomValidity (ustawia niestandardowy komunikat o błędzie). Razem pozwalają dostosować komunikaty, zachowując natywny sposób ich prezentacji.

checkValidity() po cichu zwraca true/false — bez efektów ubocznych w interfejsie. reportValidity() wykonuje to samo sprawdzenie, ale dodatkowo ustawia fokus na pierwszym nieprawidłowym polu i wyświetla podpowiedź walidacyjną przeglądarki. Należy wybrać reportValidity, gdy chcą Państwo bez dodatkowej pracy korzystać z natywnego UX.

W wieloetapowych formularzach należy sprawdzać pola danego kroku przed przejściem dalej: if (step.reportValidity()) { next(); }. Przeglądarka zajmuje się wyświetlaniem błędów, a fokus użytkownika trafia na pole wymagające uwagi — nie trzeba ponownie implementować zarządzania fokusem.

Domyślne komunikaty ("Please fill out this field") mogą nie pasować do przyjętego tonu. input.setCustomValidity("Username is required") zastępuje domyślny komunikat własnym tekstem. Pole jest traktowane jako nieprawidłowe, dopóki komunikat nie zostanie wyczyszczony.

input.setCustomValidity("") usuwa niestandardowy komunikat i ponownie włącza zwykłą walidację. Należy wywoływać tę metodę przy każdej ponownej walidacji, ponieważ w przeciwnym razie nieaktualne komunikaty niestandardowe pozostaną nawet po naprawieniu problemu przez użytkownika.

W przypadku kontroli po stronie serwera (np. unikatowości nazwy użytkownika lub ważności kuponu) należy użyć setCustomValidity po otrzymaniu odpowiedzi asynchronicznej: const ok = await checkUsername(value); input.setCustomValidity(ok ? "" : "Already taken");. Przeglądarka natychmiast uwzględni nowy stan walidacji.

Aby używać własnego sposobu wyświetlania błędów i jednocześnie korzystać ze śledzenia stanu walidacji, należy nasłuchiwać zdarzenia invalid i wywołać e.preventDefault(), aby wyłączyć natywną podpowiedź: input.addEventListener("invalid", (e) => { e.preventDefault(); showError(input, input.validationMessage); }).

setCustomValidity obsługuje jednocześnie tylko jeden niestandardowy komunikat. Aby wymusić kilka reguł, należy sprawdzić każdą z nich i wywołać setCustomValidity z najbardziej istotnym komunikatem, zgodnie z ustaloną kolejnością. Wyświetlona zostanie informacja o pierwszej niespełnionej regule.

Jeśli ustawią Państwo niestandardowy komunikat dla pustego wymaganego pola, Państwa komunikat i domyślny komunikat mogą się wzajemnie nakładać. Należy wybrać jedno podejście dla każdego pola: wyłączyć wbudowane ograniczenie (użyć type="text" zamiast type="email" i przeprowadzać walidację za pomocą setCustomValidity) albo w pełni zaufać walidacji wbudowanej.

W przypadku walidacji zależnej od wielu pól (np. zgodności potwierdzenia hasła z hasłem) należy zastosować setCustomValidity do powiązanego pola: confirmInput.setCustomValidity(confirmInput.value === passInput.value ? "" : "Passwords do not match"). Formularz pozostanie nieprawidłowy, dopóki obie wartości nie będą zgodne.

Wbudowane komunikaty są lokalizowane przez przeglądarkę na podstawie języka użytkownika. W przypadku niestandardowych komunikatów ustawianych za pomocą setCustomValidity trzeba samodzielnie zadbać o właściwy język — należy odczytać navigator.language lub własny stan i18n, a następnie dostarczyć odpowiednie tłumaczenie.

Należy otworzyć DevTools i sprawdzić każdą ścieżkę prowadzącą do błędu: wysłanie pustego formularza, częściowe dane, niezgodność formatu oraz niepowodzenie operacji asynchronicznej. Trzeba zweryfikować, czy wyświetlany jest właściwy komunikat, czy naprawienie problemu go usuwa oraz czy wysłanie prawidłowego formularza przebiega pomyślnie. Przypadki brzegowe (wklejenie danych w nieprawidłowym formacie i autouzupełnianie przeglądarki) wymagają osobnych testów.

Po wywołaniu input.setCustomValidity("Already taken") jak poinformować przeglądarkę, że pole znów jest prawidłowe?

reportValidity uruchamia wbudowany interfejs walidacji przeglądarki (fokus i podpowiedź), dzięki czemu świetnie nadaje się do programowych kontroli. setCustomValidity zastępuje domyślne komunikaty własnym tekstem — po ponownym uzyskaniu prawidłowości należy wyczyścić komunikat pustym ciągiem. Nasłuchiwanie zdarzenia invalid z użyciem preventDefault pozwala całkowicie przejąć wyświetlanie błędów. Mechanizmy te można stosować do walidacji zależnej od wielu pól, kontroli asynchronicznych i lokalizowanych komunikatów niestandardowych.