Mistrzowskie opanowanie walidacji formularzy za pomocą React `experimental_useFormStatus`

Formularze są podstawą interakcji internetowych. Od prostego zapisu do newslettera po złożoną, wieloetapową aplikację finansową, stanowią one główny kanał komunikacji użytkowników z naszymi aplikacjami. Jednak od lat zarządzanie stanem formularzy w React było źródłem złożoności, powtarzalnego kodu i zmęczenia zależnościami. Żonglowaliśmy kontrolowanymi komponentami, walczyliśmy z bibliotekami zarządzania stanem i pisaliśmy niezliczone handlery `onChange`, a wszystko to w pogoni za płynnym i intuicyjnym doświadczeniem użytkownika.

Zespół React przemyślał ten fundamentalny aspekt tworzenia stron internetowych, co doprowadziło do wprowadzenia nowego, potężnego paradygmatu skoncentrowanego wokół React Server Actions. Ten nowy model, zbudowany na zasadach progressive enhancement, ma na celu uproszczenie obsługi formularzy poprzez przeniesienie logiki bliżej miejsca, do którego należy — często serwera. Sercem tej rewolucji po stronie klienta są dwa nowe eksperymentalne hooki: `useFormState` i gwiazda naszej dzisiejszej dyskusji, `experimental_useFormStatus`.

Ten wszechstronny przewodnik zabierze Cię w głęboką podróż po hooku `experimental_useFormStatus`. Nie będziemy patrzeć tylko na jego składnię; zbadamy model mentalny, który umożliwia: Logikę walidacji opartą na statusie. Dowiesz się, jak ten hook oddziela interfejs użytkownika od stanu formularza, upraszcza zarządzanie stanami oczekującymi i współpracuje z akcjami serwerowymi, aby tworzyć solidne, dostępne i wysoce wydajne formularze, które działają nawet przed załadowaniem JavaScript.

Zmiana paradygmatu: Ewolucja formularzy React

Aby w pełni docenić innowacyjność, jaką wnosi `useFormStatus`, musimy najpierw zrozumieć historię zarządzania formularzami w ekosystemie React. Ten kontekst uwypukla problemy, które to nowe podejście elegancko rozwiązuje.

Stara Gwardia: Kontrolowane Komponenty i Biblioteki Zewnętrzne

Przez lata standardowym podejściem do formularzy w React był wzorzec kontrolowanego komponentu. To obejmuje:

• Używanie zmiennej stanu React (np. z `useState`) do przechowywania wartości każdego pola formularza.
• Pisanie handlera `onChange` do aktualizacji stanu przy każdym naciśnięciu klawisza.
• Przekazywanie zmiennej stanu z powrotem do właściwości `value` pola.

Chociaż daje to React pełną kontrolę nad stanem formularza, wprowadza znaczną ilość powtarzalnego kodu. Dla formularza z dziesięcioma polami możesz potrzebować dziesięciu zmiennych stanu i dziesięciu funkcji obsługi. Zarządzanie walidacją, stanami błędów i stanem przesyłania dodaje jeszcze więcej złożoności, co często prowadzi programistów do tworzenia skomplikowanych niestandardowych hooków lub sięgania po kompleksowe biblioteki zewnętrzne.

Biblioteki takie jak Formik i React Hook Form zyskały popularność, abstrahując od tej złożoności. Zapewniają genialne rozwiązania do zarządzania stanem, walidacji i optymalizacji wydajności. Reprezentują jednak kolejną zależność do zarządzania i często działają całkowicie po stronie klienta, co może prowadzić do duplikacji logiki walidacji między frontendem a backendem.

Nowa Era: Progressive Enhancement i Server Actions

React Server Actions wprowadzają zmianę paradygmatu. Podstawową ideą jest budowanie na fundamencie platformy internetowej: standardowym elemencie HTML `

`. Formularz z akcją serwerową działa jak klasyczne przesyłanie formularza HTML — może działać idealnie, nawet jeśli JavaScript zawiedzie lub jest wyłączony. To jest esencja progressive enhancement.

Gdy JavaScript się załaduje, React przejmuje proces przesyłania formularza, zapobiegając przeładowaniu całej strony i asynchronicznie wykonując akcję serwerową. Daje nam to to, co najlepsze z obu światów: odporność aplikacji renderowanych po stronie serwera i bogate, interaktywne doświadczenie aplikacji jednostronicowej (SPA).

Ten model przenosi źródło prawdy dla logiki biznesowej i walidacji z powrotem na serwer (lub środowisko serwerowe). Kod po stronie klienta staje się prostszy, zajmując się głównie renderowaniem interfejsu użytkownika na podstawie *statusu* tej komunikacji z serwerem. To właśnie tutaj wchodzi do gry `useFormStatus`.

Pod Maską: Czym jest `experimental_useFormStatus`?

Hook `experimental_useFormStatus` to narzędzie po stronie klienta, zaprojektowane w celu dostarczania informacji o ostatnim przesłaniu elementu `` rodzica. Jest to hook tylko do odczytu, który informuje komponent o wszystkim, co musi wiedzieć o statusie przesyłania formularza, bez potrzeby przekazywania żadnych właściwości.

Podstawowa Funkcjonalność

Wyobraź sobie przycisk przesyłania wewnątrz dużego formularza. Skąd ten przycisk wie, kiedy formularz jest przesyłany? Tradycyjnie musiałbyś przekazać zmienną stanu, taką jak `isSubmitting`, przez wiele warstw komponentów (prop drilling). Dzięki `useFormStatus` komponent przycisku może samodzielnie znaleźć te informacje.

Hook musi być wywoływany z komponentu, który jest renderowany wewnątrz elementu ``. Następnie dostarcza informacje o statusie konkretnego cyklu życia tego formularza.

Anatomia Hooku `useFormStatus`

Kiedy wywołujesz `const status = useFormStatus()`, otrzymujesz obiekt z następującymi kluczowymi właściwościami:

• `pending` (boolean): To jest najczęściej używana właściwość. Ma wartość `true`, jeśli formularz nadrzędny jest aktualnie przesyłany, a `false` w przeciwnym razie. Jest idealny do wyłączania przycisków, wyświetlania spinnerów ładowania lub stylizowania stanów oczekujących.
• `data` (FormData): Obiekt implementujący interfejs `FormData`. Zawiera dane, które zostały przesłane z formularzem. Jest to niezwykle przydatne do implementacji optymistycznych aktualizacji interfejsu użytkownika — na przykład wyświetlania komentarza użytkownika na liście natychmiast po jego przesłaniu, jeszcze zanim serwer potwierdzi jego utworzenie.
• `method` (string): Metoda HTTP ('get' lub 'post') używana do przesyłania formularza.
• `action` (function): Odniesienie do funkcji akcji serwerowej, która została wywołana podczas przesyłania.

Złota Zasada: Potomek ``

Krytyczną zasadą, o której należy pamiętać, jest to, że komponent używający `useFormStatus` musi być renderowany jako element potomny elementu ``, który śledzi. Nie może znajdować się w tym samym komponencie, który renderuje sam tag ``, ponieważ musi mieć dostęp do kontekstu formularza. Dlatego prawie zawsze zobaczysz komponenty takie jak `` utworzone oddzielnie w celu umieszczenia logiki `useFormStatus`.

Prosty Przykład: Inteligentny Przycisk Przesyłania

Zobaczmy najczęstszy przypadek użycia w akcji. Zamiast standardowego ``, utworzymy komponent, który jest świadomy stanu przesyłania formularza.

Plik: SubmitButton.js

import { experimental_useFormStatus as useFormStatus } from 'react-dom'; export function SubmitButton() { const { pending } = useFormStatus(); return (

{pending ? 'Wysyłanie...' : 'Zapisz się'} ); }

Plik: SignUpForm.js

import { SubmitButton } from './SubmitButton'; import { signUpAction } from './actions'; // Akcja serwerowa export function SignUpForm() { return ( Email:
); }

W tym przykładzie `SubmitButton` jest całkowicie samodzielny. Nie otrzymuje żadnych właściwości. Używa `useFormStatus`, aby wiedzieć, kiedy `SignUpForm` jest w stanie oczekiwania, i automatycznie się wyłącza i zmienia swój tekst. Jest to potężny wzorzec do oddzielania i tworzenia komponentów wielokrotnego użytku, świadomych formularzy.

Sedno Sprawy: Logika Walidacji Oparta na Statusie

Teraz dochodzimy do podstawowej koncepcji. `useFormStatus` służy nie tylko do stanów ładowania; jest kluczowym czynnikiem umożliwiającym inne myślenie o walidacji.

Definiowanie "Walidacji Statusu"

Walidacja Oparta na Statusie to wzorzec, w którym informacje zwrotne dotyczące walidacji są dostarczane użytkownikowi przede wszystkim w odpowiedzi na próbę przesłania formularza. Zamiast walidować przy każdym naciśnięciu klawisza (`onChange`) lub gdy użytkownik opuszcza pole (`onBlur`), podstawowa logika walidacji jest uruchamiana, gdy użytkownik przesyła formularz. Wynik tego przesłania — jego *status* (np. sukces, błąd walidacji, błąd serwera) — jest następnie używany do aktualizacji interfejsu użytkownika.

To podejście doskonale współgra z React Server Actions. Akcja serwerowa staje się jedynym źródłem prawdy dla walidacji. Otrzymuje dane formularza, waliduje je względem reguł biznesowych (np. "czy ten adres e-mail jest już w użyciu?") i zwraca obiekt stanu strukturalnego wskazujący wynik.

Rola Partnera: `experimental_useFormState`

`useFormStatus` informuje nas *co* się dzieje (oczekiwanie), ale nie mówi nam, jaki jest *wynik* tego, co się stało. Do tego potrzebujemy jego siostrzanego hooku: `experimental_useFormState`.

`useFormState` to hook zaprojektowany do aktualizacji stanu na podstawie wyniku akcji formularza. Przyjmuje funkcję akcji i stan początkowy jako argumenty i zwraca nowy stan i owiniętą funkcję akcji do przekazania do formularza.

const [state, formAction] = useFormState(myAction, initialState);

• `state`: Będzie zawierał wartość zwracaną z ostatniego wykonania `myAction`. Tutaj otrzymamy nasze komunikaty o błędach.
• `formAction`: To jest nowa wersja twojej akcji, którą powinieneś przekazać do właściwości `action` elementu `
  `. Kiedy to zostanie wywołane, uruchomi oryginalną akcję i zaktualizuje `state`.

Połączony Przepływ Pracy: Od Kliknięcia do Informacji Zwrotnej

Oto jak `useFormState` i `useFormStatus` współpracują ze sobą, aby utworzyć pełną pętlę walidacji:

1. Początkowe Renderowanie: Formularz renderuje się ze stanem początkowym dostarczonym przez `useFormState`. Nie są wyświetlane żadne błędy.
2. Przesłanie przez Użytkownika: Użytkownik klika przycisk przesyłania.
3. Stan Oczekiwania: Hook `useFormStatus` w przycisku przesyłania natychmiast zgłasza `pending: true`. Przycisk zostaje wyłączony i wyświetla komunikat o ładowaniu.
4. Wykonanie Akcji: Akcja serwerowa (owinięta przez `useFormState`) jest wykonywana z danymi formularza. Wykonuje walidację.
5. Akcja Zwraca: Akcja nie przechodzi walidacji i zwraca obiekt stanu, na przykład:
   `{ message: "Walidacja nie powiodła się", errors: { email: "Ten adres e-mail jest już zajęty." } }`
6. Aktualizacja Stanu: `useFormState` odbiera tę wartość zwracaną i aktualizuje swoją zmienną `state`. To wyzwala ponowne renderowanie komponentu formularza.
7. Informacje Zwrotne w Interfejsie Użytkownika: Formularz renderuje się ponownie. Status `pending` z `useFormStatus` zmienia się na `false`. Komponent może teraz odczytać `state.errors.email` i wyświetlić komunikat o błędzie obok pola wprowadzania adresu e-mail.

Cały ten przepływ zapewnia jasne, autorytatywne informacje zwrotne od serwera dla użytkownika, napędzane całkowicie przez status przesyłania i wynik.

Praktyczny Kurs Mistrzowski: Budowanie Formularza Rejestracyjnego z Wieloma Polami

Utrwalmy te koncepcje, budując kompletny formularz rejestracyjny w stylu produkcyjnym. Użyjemy akcji serwerowej do walidacji oraz `useFormState` i `useFormStatus`, aby stworzyć wspaniałe wrażenia użytkownika.

Krok 1: Definiowanie Akcji Serwerowej z Walidacją

Najpierw potrzebujemy naszej akcji serwerowej. Do solidnej walidacji użyjemy popularnej biblioteki Zod. Ta akcja będzie znajdować się w oddzielnym pliku, oznaczonym dyrektywą `'use server';`, jeśli używasz frameworka takiego jak Next.js.

Plik: actions/authActions.js

'use server'; import { z } from 'zod'; // Zdefiniuj schemat walidacji const registerSchema = z.object({ username: z.string().min(3, 'Nazwa użytkownika musi mieć co najmniej 3 znaki.'), email: z.string().email('Proszę wprowadzić prawidłowy adres e-mail.'), password: z.string().min(8, 'Hasło musi mieć co najmniej 8 znaków.'), }); // Zdefiniuj stan początkowy dla naszego formularza export const initialState = { message: '', errors: {}, }; export async function registerUser(prevState, formData) { // 1. Waliduj dane formularza const validatedFields = registerSchema.safeParse( Object.fromEntries(formData.entries()) ); // 2. Jeśli walidacja się nie powiedzie, zwróć błędy if (!validatedFields.success) { return { message: 'Walidacja nie powiodła się. Proszę sprawdzić pola.', errors: validatedFields.error.flatten().fieldErrors, }; } // 3. (Symulacja) Sprawdź, czy użytkownik już istnieje w bazie danych // W prawdziwej aplikacji zapytałbyś tutaj swoją bazę danych. if (validatedFields.data.email === 'user@example.com') { return { message: 'Rejestracja nie powiodła się.', errors: { email: ['Ten adres e-mail jest już zarejestrowany.'] }, }; } // 4. (Symulacja) Utwórz użytkownika console.log('Tworzenie użytkownika:', validatedFields.data); // 5. Zwróć stan sukcesu // W prawdziwej aplikacji możesz przekierować tutaj za pomocą `redirect()` z 'next/navigation' return { message: 'Użytkownik zarejestrowany pomyślnie!', errors: {}, }; }

Ta akcja serwerowa jest mózgiem naszego formularza. Jest samodzielna, bezpieczna i zapewnia przejrzystą strukturę danych zarówno dla stanów sukcesu, jak i błędów.

Krok 2: Budowanie Komponentów Wielokrotnego Użytku, Świadomych Statusu

Aby nasz główny komponent formularza był czysty, utworzymy dedykowane komponenty dla naszych pól wprowadzania i przycisku przesyłania.

Plik: components/SubmitButton.js

'use client'; import { experimental_useFormStatus as useFormStatus } from 'react-dom'; export function SubmitButton({ label }) { const { pending } = useFormStatus(); return ( {pending ? 'Przetwarzanie...' : label} ); }

Zwróć uwagę na użycie `aria-disabled={pending}`. Jest to ważna praktyka dostępności, zapewniająca, że czytniki ekranu poprawnie ogłaszają stan wyłączenia.

Krok 3: Składanie Głównego Formularza z `useFormState`

Teraz połączmy wszystko w naszym głównym komponencie formularza. Użyjemy `useFormState`, aby połączyć nasz interfejs użytkownika z akcją `registerUser`.

Plik: components/RegistrationForm.js

'use client'; import { experimental_useFormState as useFormState } from 'react-dom'; import { registerUser, initialState } from '../actions/authActions'; import { SubmitButton } from './SubmitButton'; export function RegistrationForm() { const [state, formAction] = useFormState(registerUser, initialState); return (

Zarejestruj się

{state?.message && !state.errors &&

{state.message}

} {state?.message && state.errors &&

{state.message}

}

Nazwa użytkownika {state?.errors?.username && (

{state.errors.username[0]}

)}

Email {state?.errors?.email && (

{state.errors.email[0]}

)}

Hasło {state?.errors?.password && (

{state.errors.password[0]}

)}

); }

Ten komponent jest teraz deklaratywny i czysty. Nie zarządza żadnym stanem samodzielnie, poza obiektem `state` dostarczonym przez `useFormState`. Jego jedynym zadaniem jest renderowanie interfejsu użytkownika na podstawie tego stanu. Logika wyłączania przycisku jest hermetyzowana w `SubmitButton`, a cała logika walidacji znajduje się w `authActions.js`. To oddzielenie problemów to ogromna korzyść dla łatwości konserwacji.

Zaawansowane Techniki i Profesjonalne Najlepsze Praktyki

Chociaż podstawowy wzorzec jest potężny, rzeczywiste aplikacje często wymagają więcej niuansów. Zbadajmy kilka zaawansowanych technik.

Podejście Hybrydowe: Łączenie Walidacji Natychmiastowej i Po Przesłaniu

Walidacja oparta na statusie jest doskonała do sprawdzania po stronie serwera, ale czekanie na podróż w obie strony po sieci, aby poinformować użytkownika, że jego adres e-mail jest nieprawidłowy, może być powolne. Często najlepsze jest podejście hybrydowe:

• Użyj Walidacji HTML5: Nie zapomnij o podstawach! Atrybuty takie jak `required`, `type="email"`, `minLength` i `pattern` zapewniają natychmiastowe, natywne dla przeglądarki informacje zwrotne bez żadnych kosztów.
• Lekka Walidacja po Stronie Klienta: W przypadku czysto kosmetycznych lub formatujących kontroli (np. wskaźnik siły hasła) nadal możesz użyć minimalnej ilości `useState` i handlerów `onChange`.
• Autorytet po Stronie Serwera: Zarezerwuj akcję serwerową dla najważniejszej, biznesowej logiki walidacji, której nie można wykonać po stronie klienta (np. sprawdzanie unikalnych nazw użytkowników, walidacja względem rekordów bazy danych).

Daje to to, co najlepsze z obu światów: natychmiastowe informacje zwrotne dotyczące prostych błędów i autorytatywną walidację złożonych reguł.

Dostępność (A11y): Tworzenie Formularzy dla Wszystkich

Dostępność nie podlega negocjacjom. Podczas implementacji walidacji opartej na statusie pamiętaj o tych punktach:

• Ogłaszaj Błędy: W naszym przykładzie użyliśmy `aria-live="polite"` na kontenerach komunikatów o błędach. To mówi czytnikom ekranu, aby ogłosiły komunikat o błędzie, gdy tylko się pojawi, bez przerywania bieżącego przepływu użytkownika.
• Powiąż Błędy z Polami Wprowadzania: Aby uzyskać bardziej solidne połączenie, użyj atrybutu `aria-describedby`. Pole wprowadzania może wskazywać identyfikator kontenera komunikatów o błędach, tworząc programowe łącze.
• Zarządzanie Focusem: Po przesłaniu z błędami rozważ programowe przeniesienie fokusa na pierwsze nieprawidłowe pole. To oszczędza użytkownikom szukania, co poszło nie tak.

Optymistyczny Interfejs Użytkownika z Właściwością `data` z `useFormStatus`

Wyobraź sobie aplikację społecznościową, w której użytkownik publikuje komentarz. Zamiast wyświetlać spinner przez sekundę, możesz sprawić, by aplikacja wydawała się natychmiastowa. Właściwość `data` z `useFormStatus` jest do tego idealna.

Gdy formularz zostanie przesłany, `pending` staje się prawdą, a `data` jest wypełniana `FormData` przesłania. Możesz natychmiast renderować nowy komentarz w tymczasowym, „oczekującym” stanie wizualnym, używając tych `data`. Jeśli akcja serwerowa się powiedzie, zastępujesz oczekujący komentarz ostatecznymi danymi z serwera. Jeśli się nie powiedzie, możesz usunąć oczekujący komentarz i wyświetlić błąd. To sprawia, że aplikacja wydaje się niesamowicie responsywna.

Nawigacja po "Eksperymentalnych" Wodach

Konieczne jest odniesienie się do przedrostka „eksperymentalny” w `experimental_useFormStatus` i `experimental_useFormState`.

Co Naprawdę Oznacza "Eksperymentalny"

Kiedy React określa API jako eksperymentalne, oznacza to:

• API może się zmienić: Nazwa, argumenty lub wartości zwracane mogą zostać zmienione w przyszłej wersji React bez przestrzegania standardowego wersjonowania semantycznego (SemVer) dla zmian powodujących niezgodność.
• Mogą występować błędy: Jako nowa funkcja może mieć przypadki brzegowe, które nie są jeszcze w pełni zrozumiałe lub rozwiązane.
• Dokumentacja może być rzadka: Chociaż podstawowe koncepcje są udokumentowane, szczegółowe przewodniki po zaawansowanych wzorcach mogą nadal ewoluować.

Kiedy Przyjąć, a Kiedy Poczekać

Czy powinieneś więc używać go w swoim projekcie? Odpowiedź zależy od twojego kontekstu:

• Dobre dla: Projektów osobistych, narzędzi wewnętrznych, startupów lub zespołów, którym wygodnie jest zarządzać potencjalnymi zmianami API. Używanie go w ramach frameworka takiego jak Next.js (który zintegrował te funkcje z App Router) jest ogólnie bezpieczniejsze, ponieważ framework może pomóc w abstrahowaniu niektórych zmian.
• Używaj z Ostrożnością dla: Aplikacji korporacyjnych na dużą skalę, systemów o krytycznym znaczeniu lub projektów z długoterminowymi umowami serwisowymi, w których stabilność API jest najważniejsza. W takich przypadkach może być roztropniej poczekać, aż hooki zostaną awansowane do stabilnego API.

Zawsze obserwuj oficjalny blog React i dokumentację, aby uzyskać ogłoszenia dotyczące stabilizacji tych hooków.

Wnioski: Przyszłość Formularzy w React

Wprowadzenie `experimental_useFormStatus` i powiązanych z nim API to coś więcej niż tylko nowe narzędzie; reprezentuje filozoficzną zmianę w sposobie budowania interaktywnych doświadczeń za pomocą React. Przyjmując fundamenty platformy internetowej i umieszczając logikę stanową na serwerze, możemy budować aplikacje, które są prostsze, bardziej odporne i często wydajniejsze.

Widzieliśmy, jak `useFormStatus` zapewnia czysty, oddzielony sposób dla komponentów na reagowanie na cykl życia przesyłania formularza. Eliminuje prop drilling dla stanów oczekujących i umożliwia eleganckie, samodzielne komponenty interfejsu użytkownika, takie jak inteligentny `SubmitButton`. W połączeniu z `useFormState` odblokowuje potężny wzorzec walidacji opartej na statusie, gdzie serwer jest ostatecznym autorytetem, a głównym zadaniem klienta jest renderowanie stanu zwróconego przez akcję serwerową.

Chociaż tag „eksperymentalny” uzasadnia pewien stopień ostrożności, kierunek jest jasny. Przyszłość formularzy w React to progressive enhancement, uproszczone zarządzanie stanem i potężna, bezproblemowa integracja logiki klienta i serwera. Opanowując te nowe hooki dzisiaj, nie tylko uczysz się nowego API; przygotowujesz się na następną generację tworzenia aplikacji internetowych za pomocą React.