ההוק useActionState ב-React: טפסים, שגיאות ו-pending

useActionState הוא הוק של React 19 שמריץ פונקציה async (action), שומר את מה שהיא מחזירה כ-state, ואומר לכם אם היא עדיין רצה. קוראים לו בתור const [state, formAction, isPending] = useActionState(action, initialState) ומעבירים את formAction ל-<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>
    );
}

שלחו קודם את הטופס הריק: ה-action מחזיר אובייקט שגיאה וההודעה מופיעה. אחר כך הקלידו כתובת עם @ ושלחו שוב. לשנייה על הכפתור כתוב "Subscribing..." והוא מושבת.

התחביר

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

• action היא הפונקציה להרצה. React קוראת לה בתור action(previousState, ...args). מה שהיא מחזירה (או מסתיימת איתו, אם היא async) הופך ל-state החדש.
• initialState הוא ה-state לפני שה-action רץ אי פעם. השתמשו באותה צורה שה-action מחזיר, כדי שהקומפוננטה תוכל לקרוא את state.message גם ברינדור הראשון.
• state הוא התוצאה האחרונה.
• formAction היא גרסה עטופה של ה-action שלכם. העבירו אותה ל-<form action> או ל-<button formAction>, או קראו לה בעצמכם.
• isPending הוא true מהרגע שה-action מתחיל ועד שהוא מסתיים.
• permalink אופציונלי ורלוונטי רק ל-Server Functions ב-framework: הכתובת שהטופס צריך לעבור אליה אם הוא נשלח לפני ש-JavaScript נטען.

ה-action מקבל את ה-state הקודם כארגומנט הראשון שלו. זו הטעות הנפוצה ביותר כשמעבירים טופס: כתיבת async function save(formData) נותנת לכם את ה-state הישן ב-formData, ו-formData.get זורק שגיאה.

קריאת הטופס עם FormData

כש-formAction משמש כ-action של טופס, React קוראת ל-action שלכם עם ה-FormData של הטופס. כל שדה עם name נמצא בו. לא צריך useState לשדות או handler של onChange, ולא קוראים ל-e.preventDefault(): React מטפלת באירוע השליחה.

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>
    );
}

בטלו את הסימון ב-Spicy ושלחו שוב: המפתח spicy נעלם מהנתונים שנרשמו, כי checkbox לא מסומן לא שולח כלום. ה-action גם קורא את previousState.count כדי להוסיף אחד, וזו הסיבה שה-state הקודם בא ראשון.

החזרת שגיאות ולידציה

ולידציה שייכת ל-action. החזירו את השגיאות כחלק מה-state, והחזירו את הערכים שהמשתמש הקליד כדי שהטופס יוכל להחזיר אותם למקום. אחרי ש-form action מסתיים, React מאפסת את השדות הלא מבוקרים של הטופס, כך ששדה בלי defaultValue={state.values...} היה חוזר ריק אחרי שליחה שנכשלה.

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>
    );
}

הקלידו שם של אות אחת וסיסמה קצרה, ואז שלחו. שתי השגיאות מופיעות ושני השדות שומרים את מה שהקלדתם. הסירו את defaultValue={state.values.name} ושלחו שוב: שדה השם מתרוקן אחרי השגיאה.

באפליקציה אמיתית השאירו לשרת את המילה האחרונה. בדיקות בצד הלקוח נותנות משוב מהיר, אבל כל אחד יכול לשלוח בקשה בלי הטופס שלכם.

קריאה ל-action מחוץ לטופס

formAction היא פונקציה, ולכן גם כפתור או אפקט יכולים לקרוא לה. כשקוראים לה בעצמכם, עטפו את הקריאה ב-startTransition. טופס עושה את זה בשבילכם; onClick רגיל לא, ובלי transition isPending לא מתעדכן נכון (React רושמת על זה שגיאה בפיתוח).

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>
    );
}

לחצו על Load more כמה פעמים. כל קריאה מתחילה מה-state שהקודמת החזירה, כך שדפים מתווספים לפי הסדר. אם קוראים ל-action שוב בזמן שהוא עדיין רץ, React מכניסה את הקריאה לתור ומריצה אותה אחרי הנוכחית, כל אחת עם ה-state העדכני.

מאיפה useActionState הגיע

לפני ש-React 19 שוחררה, ההוק הזה היה זמין בגרסאות canary בתור useFormState, שמיובא מ-react-dom. השם שלו שונה ל-useActionState, הוא עבר ל-react, וקיבל את הערך isPending. אם אתם מוצאים קוד ישן כזה, התיקון הוא ה-import והשם:

// 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);

כדי להציג מצב pending בכפתור שליחה שמקונן עמוק, useFormStatus מ-react-dom קורא את הסטטוס של הטופס ההורה בלי props. הסקירה של React 19 מציגה אותו עם שאר יכולות הטפסים.

שגיאות ומתי להשתמש במשהו אחר

אם ה-action זורק שגיאה, React מציגה את ה-error boundary הקרוב במקום לעדכן את ה-state. לשגיאות שהמשתמש יכול לתקן, כמו ולידציה או שם משתמש תפוס, החזירו אותן כ-state, כמו בדוגמת ההרשמה. תנו לכישלונות אמיתיים לזרוק.

useActionState נועד לתוצאה של action. לערך שמתעדכן מיד בזמן שה-action רץ, כמו מונה לייקים שצריך לעלות בלחיצה, שלבו אותו עם useOptimistic. לקלט שמשתנה בכל הקשה ונקרא בזמן הרינדור, useState רגיל ושדה מבוקר הם עדיין הכלי הנכון.

טעויות נפוצות

לשכוח את פרמטר ה-state הקודם. async function save(formData) מקבלת את ה-state הקודם ב-formData. בטופס החתימה היא תמיד (previousState, formData).

שדות בלי name. FormData מכיל רק שדות שיש להם מאפיין name. שדה עם id בלבד חסר ב-formData.get(...), שמחזיר null.

שדות מבוקרים בכל מקום. עדיין אפשר להשתמש ב-value וב-onChange בתוך form action, אבל לא חייבים. שדות לא מבוקרים עם name ו-defaultValue הם ההתאמה הפשוטה יותר ל-actions, והאיפוס של React אחרי שליחה משפיע רק על שדות לא מבוקרים.

קריאת state בתוך ה-action. ה-state מהקומפוננטה הוא הערך מהרינדור שיצר את ה-handler. בתוך ה-action, השתמשו ב-previousState, שתמיד הוא התוצאה של הקריאה שלפניו, גם כשכמה קריאות נכנסו לתור.

לזרוק שגיאה על שגיאות צפויות. שגיאה שנזרקת מחליפה את הטופס ב-error boundary הקרוב. סיסמה שגויה היא לא קריסה; החזירו אותה כ-state.