Hook useActionState w React: formularze, błędy, oczekiwanie

useActionState to hook z React 19, który uruchamia funkcję async (akcję), zapisuje jako stan to, co ona zwróci, i mówi, czy nadal działa. Wywołujesz go jako const [state, formAction, isPending] = useActionState(action, initialState) i przekazujesz formAction do <form>.

import { useActionState } from 'react';

function subscribe(email) {
    // Stands in for a real request
    return new Promise((resolve) => setTimeout(resolve, 1000));
}

async function joinList(previousState, formData) {
    const email = formData.get('email');
    if (!email.includes('@')) {
        return { ok: false, message: 'That does not look like an email.' };
    }
    await subscribe(email);
    return { ok: true, message: `Subscribed ${email}.` };
}

export default function App() {
    const [state, formAction, isPending] = useActionState(joinList, { ok: false, message: '' });

    return (
        <form action={formAction}>
            <input name="email" placeholder="you@example.com" />
            <button type="submit" disabled={isPending}>
                {isPending ? 'Subscribing...' : 'Subscribe'}
            </button>
            {state.message && (
                <p style={{ color: state.ok ? 'green' : 'crimson' }}>{state.message}</p>
            )}
        </form>
    );
}

Najpierw wyślij pusty formularz: akcja zwraca obiekt błędu i pojawia się komunikat. Potem wpisz adres z @ i wyślij ponownie. Przez sekundę przycisk pokazuje "Subscribing..." i jest wyłączony.

Składnia

const [state, formAction, isPending] = useActionState(action, initialState, permalink?);

• action to funkcja do uruchomienia. React wywołuje ją jako action(previousState, ...args). To, co zwróci (albo do czego się rozwiąże, jeśli jest async), staje się nowym state.
• initialState to stan, zanim akcja kiedykolwiek się wykonała. Używaj tego samego kształtu, który zwraca akcja, żeby komponent mógł odczytać state.message także przy pierwszym renderowaniu.
• state to najnowszy wynik.
• formAction to opakowana wersja twojej akcji. Przekaż ją do <form action> albo <button formAction> albo wywołaj ją sam.
• isPending ma wartość true od chwili rozpoczęcia akcji, dopóki się nie skończy.
• permalink jest opcjonalny i ma znaczenie tylko dla funkcji serwerowych we frameworku: to adres URL, pod który powinien trafić formularz, jeśli zostanie wysłany przed załadowaniem JavaScriptu.

Akcja dostaje poprzedni stan jako pierwszy argument. To najczęstszy błąd przy przenoszeniu formularza: napisanie async function save(formData) daje ci stary stan w formData, a formData.get rzuca błąd.

Odczyt formularza przez FormData

Gdy formAction jest użyte jako action formularza, React wywołuje twoją akcję z FormData formularza. Znajduje się w nim każde pole z name. Nie potrzebujesz useState dla pól ani handlera onChange i nie wywołujesz e.preventDefault(): React sam obsługuje zdarzenie wysłania.

import { useActionState } from 'react';

async function order(previousState, formData) {
    const entries = Object.fromEntries(formData);
    console.log('form data:', entries);
    return { count: previousState.count + 1, last: entries };
}

export default function App() {
    const [state, formAction] = useActionState(order, { count: 0, last: null });

    return (
        <form action={formAction}>
            <input name="dish" defaultValue="Ramen" />
            <select name="size" defaultValue="large">
                <option value="small">Small</option>
                <option value="large">Large</option>
            </select>
            <label>
                <input type="checkbox" name="spicy" defaultChecked /> Spicy
            </label>
            <button type="submit">Order</button>
            <p>Orders placed: {state.count}</p>
            {state.last && <p>Last: {state.last.size} {state.last.dish}</p>}
        </form>
    );
}

Odznacz Spicy i wyślij ponownie: klucz spicy znika z wypisanych danych, bo niezaznaczone pole wyboru niczego nie wysyła. Akcja czyta też previousState.count, żeby dodać jeden, i dlatego poprzedni stan jest pierwszy.

Zwracanie błędów walidacji

Walidacja należy do akcji. Zwracaj błędy jako część stanu i zwracaj wpisane przez użytkownika wartości, żeby formularz mógł je przywrócić. Po zakończeniu akcji formularza React resetuje niekontrolowane pola, więc pole bez defaultValue={state.values...} wróciłoby puste po nieudanym wysłaniu.

import { useActionState } from 'react';

function createAccount(name) {
    // Stands in for a real request
    return new Promise((resolve) => setTimeout(() => resolve({ id: 7, name }), 800));
}

async function signUp(previousState, formData) {
    const values = { name: formData.get('name'), password: formData.get('password') };
    const errors = {};
    if (values.name.trim().length < 2) errors.name = 'At least 2 characters.';
    if (values.password.length < 8) errors.password = 'At least 8 characters.';
    if (Object.keys(errors).length > 0) {
        return { values, errors, user: null };
    }
    const user = await createAccount(values.name);
    return { values: { name: '', password: '' }, errors: {}, user };
}

const initial = { values: { name: '', password: '' }, errors: {}, user: null };

export default function App() {
    const [state, formAction, isPending] = useActionState(signUp, initial);

    if (state.user) return <p>Welcome, {state.user.name} (account #{state.user.id}).</p>;

    return (
        <form action={formAction} style={{ display: 'grid', gap: 6, maxWidth: 240 }}>
            <input name="name" placeholder="Name" defaultValue={state.values.name} />
            {state.errors.name && <small style={{ color: 'crimson' }}>{state.errors.name}</small>}
            <input name="password" type="password" placeholder="Password" defaultValue={state.values.password} />
            {state.errors.password && <small style={{ color: 'crimson' }}>{state.errors.password}</small>}
            <button type="submit" disabled={isPending}>{isPending ? 'Creating...' : 'Create account'}</button>
        </form>
    );
}

Wpisz jednoliterowe imię i krótkie hasło, a potem wyślij. Pojawią się oba błędy, a oba pola zachowają to, co wpisałeś. Usuń defaultValue={state.values.name} i wyślij ponownie: pole imienia opróżni się po błędzie.

W prawdziwej aplikacji ostatecznym sędzią niech będzie serwer. Sprawdzenia po stronie klienta dają szybką informację zwrotną, ale każdy może wysłać żądanie bez twojego formularza.

Wywoływanie akcji poza formularzem

formAction to funkcja, więc może ją wywołać też przycisk albo efekt. Gdy wywołujesz ją sam, owiń wywołanie w startTransition. Formularz robi to za ciebie; zwykłe onClick nie, a bez przejścia isPending nie aktualizuje się poprawnie (React wypisuje o tym błąd w trybie deweloperskim).

import { startTransition, useActionState } from 'react';

function fetchNextPage(page) {
    // Stands in for a real request
    return new Promise((resolve) =>
        setTimeout(() => resolve([`Item ${page * 2 - 1}`, `Item ${page * 2}`]), 700),
    );
}

async function loadMore(previousState) {
    const page = previousState.page + 1;
    const items = await fetchNextPage(page);
    return { page, items: [...previousState.items, ...items] };
}

export default function App() {
    const [state, load, isPending] = useActionState(loadMore, { page: 0, items: [] });

    return (
        <div>
            <ul>
                {state.items.map((item) => (
                    <li key={item}>{item}</li>
                ))}
            </ul>
            <button onClick={() => startTransition(() => load())} disabled={isPending}>
                {isPending ? 'Loading...' : 'Load more'}
            </button>
        </div>
    );
}

Kliknij kilka razy Load more. Każde wywołanie zaczyna od stanu, który zwróciło poprzednie, więc strony są dopisywane po kolei. Jeśli wywołasz akcję ponownie, gdy jeszcze działa, React ustawi wywołanie w kolejce i uruchomi je po bieżącym, każde z najnowszym stanem.

Skąd się wziął useActionState

Zanim wydano React 19, ten hook był dostępny w wersjach canary jako useFormState, importowany z react-dom. Zmieniono mu nazwę na useActionState, przeniesiono go do react i dodano wartość isPending. Jeśli znajdziesz taki stary kod, poprawka dotyczy importu i nazwy:

// React canary, before 19
import { useFormState } from 'react-dom';
const [state, formAction] = useFormState(action, initialState);

// React 19
import { useActionState } from 'react';
const [state, formAction, isPending] = useActionState(action, initialState);

Żeby pokazać stan oczekiwania w głęboko zagnieżdżonym przycisku wysyłania, useFormStatus z react-dom odczytuje status formularza rodzica bez propsów. Przegląd React 19 wymienia go razem z innymi funkcjami formularzy.

Błędy i kiedy użyć czegoś innego

Jeśli akcja rzuci błąd, React zamiast aktualizować stan pokaże najbliższą granicę błędów. Błędy, które użytkownik może poprawić, takie jak walidacja albo zajęta nazwa użytkownika, zwracaj jako stan, jak w przykładzie z rejestracją. Prawdziwe awarie niech rzucają błąd.

useActionState służy do wyniku akcji. Dla wartości, która aktualizuje się natychmiast w trakcie działania akcji, na przykład licznika polubień, który ma wzrosnąć po kliknięciu, połącz go z useOptimistic. Dla danych wejściowych, które zmieniają się przy każdym naciśnięciu klawisza i są czytane podczas renderowania, właściwym narzędziem nadal są zwykłe useState i kontrolowane pole.

Częste błędy

Zapomnienie o parametrze poprzedniego stanu. async function save(formData) dostaje poprzedni stan w formData. Dla formularza sygnatura to zawsze (previousState, formData).

Pola bez name. FormData zawiera tylko pola, które mają atrybut name. Pola z samym id brakuje w formData.get(...), które zwraca wtedy null.

Kontrolowane pola wszędzie. Wewnątrz akcji formularza nadal możesz używać value i onChange, ale nie musisz. Niekontrolowane pola z name i defaultValue prościej pasują do akcji, a reset Reacta po wysłaniu dotyczy tylko pól niekontrolowanych.

Odczyt stanu wewnątrz akcji. state z komponentu to wartość z renderowania, które utworzyło handler. Wewnątrz akcji używaj previousState, który zawsze jest wynikiem poprzedniego wywołania, nawet gdy kilka wywołań stało w kolejce.

Rzucanie błędów dla przewidywalnych sytuacji. Rzucony błąd zastępuje formularz najbliższą granicą błędów. Złe hasło to nie awaria; zwróć je jako stan.