الخطاف useActionState في React: النماذج والأخطاء والانتظار

useActionState خطاف في React 19 يشغّل دالة غير متزامنة (إجراءً)، ويخزّن ما تُرجعه كحالة، ويخبرك ما إذا كانت ما زالت تعمل. تستدعيه على شكل 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>
    );
}

أرسل النموذج فارغًا أولًا: يُرجع الإجراء كائن خطأ وتظهر الرسالة. ثم اكتب عنوانًا فيه @ وأرسل مرة أخرى. لثانية يقرأ الزر "Subscribing..." ويكون معطّلًا.

الصيغة

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

• action هي الدالة التي تعمل. تستدعيها React على شكل action(previousState, ...args). وما تُرجعه (أو ما تُحل إليه، إذا كانت غير متزامنة) يصبح state الجديدة.
• initialState هي الحالة قبل أن يعمل الإجراء أبدًا. استخدم الشكل نفسه الذي يُرجعه الإجراء، ليتمكن المكوّن من قراءة state.message في العرض الأول أيضًا.
• state هي أحدث نتيجة.
• formAction نسخة مغلّفة من إجرائك. مررها إلى <form action> أو <button formAction>، أو استدعِها بنفسك.
• تكون isPending قيمتها true من لحظة بدء الإجراء حتى ينتهي.
• permalink اختيارية ولا تهم إلا لدوال الخادم في إطار عمل: عنوان URL الذي ينبغي أن يذهب إليه النموذج إذا أُرسل قبل تحميل JavaScript.

يستقبل الإجراء الحالة السابقة كوسيطه الأول. هذا أشيع خطأ عند نقل نموذج: كتابة async function save(formData) تعطيك الحالة القديمة في formData، فيرمي formData.get خطأ.

قراءة النموذج بـ FormData

عندما تُستخدم formAction على أنها action النموذج، تستدعي React إجراءك مع FormData الخاص بالنموذج. كل حقل له name موجود فيه. لا تحتاج إلى useState للحقول ولا إلى معالج 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 من البيانات المسجّلة، لأن مربع الاختيار غير المحدد لا يرسل شيئًا. ويقرأ الإجراء أيضًا previousState.count ليضيف واحدًا، ولهذا تأتي الحالة السابقة أولًا.

إرجاع أخطاء التحقق

مكان التحقق هو الإجراء. أرجع الأخطاء كجزء من الحالة، وأرجع القيم التي كتبها المستخدم ليتمكن النموذج من إعادتها. بعد انتهاء إجراء النموذج، تعيد 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} وأرسل مرة أخرى: يفرّغ حقل الاسم نفسه بعد الخطأ.

في تطبيق حقيقي أبقِ الخادم هو الحكم النهائي. تعطي فحوص العميل ملاحظات سريعة، لكن أي شخص يستطيع إرسال طلب دون نموذجك.

استدعاء الإجراء خارج نموذج

formAction دالة، فيستطيع زر أو تأثير استدعاءها أيضًا. عندما تستدعيها بنفسك، غلّف الاستدعاء في startTransition. يفعل النموذج ذلك نيابة عنك؛ أما onClick العادي فلا، ومن دون انتقال لا تتحدث 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 بضع مرات. كل استدعاء يبدأ من الحالة التي أرجعها السابق، فتُلحق الصفحات بالترتيب. وإذا استدعيت الإجراء مرة أخرى وهو ما زال يعمل، تضع React الاستدعاء في طابور وتشغّله بعد الحالي، كل منها بأحدث حالة.

من أين جاء useActionState

قبل صدور React 19، كان هذا الخطاف متاحًا في نسخ canary باسم useFormState، مستوردًا من react-dom. ثم أُعيدت تسميته إلى useActionState، ونُقل إلى react، وأُعطي القيمة isPending. إذا وجدت كودًا قديمًا مثل هذا، فالإصلاح هو الاستيراد والاسم:

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

ولعرض حالة انتظار في زر إرسال متداخل بعمق، يقرأ useFormStatus من react-dom حالة النموذج الأب دون props. تسرده نظرة عامة على React 19 مع ميزات النماذج الأخرى.

الأخطاء ومتى تستخدم شيئًا آخر

إذا رمى الإجراء خطأ، تعرض React أقرب حدود أخطاء بدلًا من تحديث الحالة. أما الأخطاء التي يستطيع المستخدم إصلاحها، مثل التحقق أو اسم مستخدم محجوز، فأرجعها كحالة، كما في مثال التسجيل. ودع الأعطال الحقيقية ترمي.

useActionState مخصص لنتيجة إجراء. ولقيمة تتحدث فورًا أثناء عمل الإجراء، مثل عدد إعجابات ينبغي أن يرتفع عند النقر، اجمعه مع useOptimistic. وللإدخال الذي يتغير مع كل ضغطة مفتاح ويُقرأ أثناء العرض، ما زال useState العادي مع حقل متحكم به الأداة المناسبة.

أخطاء شائعة

نسيان معامل الحالة السابقة. تستقبل async function save(formData) الحالة السابقة في formData. التوقيع في النموذج دائمًا (previousState, formData).

حقول بلا name. لا يحتوي FormData إلا على الحقول التي لها سمة name. الحقل الذي ليس له إلا id غائب عن formData.get(...)، فتُرجع null.

حقول متحكم بها في كل مكان. ما زال بإمكانك استخدام value وonChange داخل إجراء نموذج، لكنك لست مضطرًا. الحقول غير المتحكم بها مع name وdefaultValue أبسط توافقًا مع الإجراءات، وإعادة الضبط التي تجريها React بعد الإرسال لا تؤثر إلا في الحقول غير المتحكم بها.

قراءة state داخل الإجراء. قيمة state من المكوّن هي القيمة من العرض الذي أنشأ المعالج. داخل الإجراء استخدم previousState، التي تكون دائمًا نتيجة الاستدعاء الذي قبله، حتى عندما توضع عدة استدعاءات في طابور.

رمي أخطاء للحالات المتوقعة. الخطأ المرمي يستبدل النموذج بأقرب حدود أخطاء. كلمة المرور الخاطئة ليست انهيارًا؛ أرجعها كحالة.