useActionState وuseFormStatus

إن useActionState(action, initialState) هو خطاف في React 19 يغلّف إجراءً من إجراءات الخادم لتتبّع حالته بين عمليات الإرسال. ويتلقى دالة الإجراء وقيمة حالة أولية، ثم يعيد صفيفًا ثلاثيًا يمكنكم استخدامه للتحكم في تجربة النموذج بأكملها.

يعيد الخطاف [state, formAction, isPending]. وتحتوي state على أحدث قيمة أعادها الإجراء، وتبدأ بقيمة null أو بالقيمة الأولية التي حددتموها. أما formAction فهو الإجراء المغلّف الذي تمررونه إلى النموذج. وتكون isPending مساوية لـ true أثناء تنفيذ الإجراء على الخادم.

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

إذا أعاد إجراء الخادم القيمة { errors: { email: 'Invalid email' } }، فيمكنكم عرض الخطأ داخل النموذج: {state.errors?.email && <p>{state.errors.email}</p>}. وبما أن الحالة تستمر بين عمليات إعادة العرض، تظل رسالة الخطأ ظاهرة حتى تستبدلها عملية إرسال ناجحة تالية بالحالة الجديدة.

عندما يعيد الإجراء { success: true }، يمكن للمكوّن عرض رسالة نجاح: {state?.success && <p>Form submitted!</p>}. ويمكن إخفاء النموذج أو استبداله برسالة النجاح بشكل مشروط استنادًا إلى قيمة الحالة.

إن useFormStatus() هو خطاف يقرأ حالة الانتظار لعنصر <form> الأقرب إليه في شجرة المكوّنات. ويعيد كائنًا يتضمن { pending: boolean }. ويجب استخدام هذا الخطاف داخل مكوّن يكون ابنًا للنموذج، وليس داخل المكوّن الذي يعرض النموذج نفسه.

يوجد شرط استخدام useFormStatus داخل النموذج لأن الخطاف يقرأ سياق النموذج من شجرة React الموجودة فوقه. وإذا استُدعي في المكوّن نفسه الذي يعرض النموذج، فسيكون شقيقًا للنموذج لا نسلًا له، ولن يتمكن من الوصول إلى حالة النموذج.

يتمثل النمط القياسي في استخراج زر الإرسال إلى مكوّن مستقل: function SubmitButton() { const { pending } = useFormStatus(); return <button disabled={pending}>Submit</button>; }. ثم يوضع هذا المكوّن داخل النموذج، مما يمنحه إمكانية الوصول إلى حالة انتظار النموذج.

يمنع ضبط disabled={pending} في زر الإرسال عمليات الإرسال المزدوجة. فعندما ينقر المستخدم على زر الإرسال ويكون إجراء الخادم قيد التنفيذ، تكون قيمة pending هي true، فيُعطَّل الزر ولا يعود قابلًا للنقر. وعند اكتمال الإجراء، تعود قيمة pending إلى false ويُعاد تفعيل الزر.

يجمع نمط تجربة النموذج الكامل بين الخطافين: إذ يتتبّع useActionState في مكوّن النموذج نتيجة الإجراء ويوفر formAction، بينما يتتبّع useFormStatus داخل مكوّن ابن يُسمى SubmitButton حالة الانتظار. ويوفر الخطافان معًا عرض أخطاء التحقق وزر إرسال سريع الاستجابة.

للحصول على استجابة أسرع، يتكامل useOptimistic مع useActionState. إذ تحدّثون واجهة المستخدم فورًا بالنتيجة المتوقعة قبل استجابة الخادم، ثم تزامنونها عند وصول الاستجابة الفعلية. ويشيع هذا النمط في أزرار الإعجاب وقوائم المهام والتفاعلات الأخرى التي تتطلب استجابة سريعة.

أين يجب استدعاء useFormStatus حتى يعمل بشكل صحيح؟

يعيد useActionState(action, initialState) القيمة [state, formAction, isPending] لتتبّع نتائج إجراءات الخادم. وتحتوي الحالة على القيمة التي أعادها الإجراء، مما يتيح عرض الأخطاء والنجاح داخل النموذج. ويوفر useFormStatus() القيمة { pending } داخل المكوّنات الابنة للنموذج، مما يتيح إنشاء أزرار إرسال سريعة الاستجابة. وينشئ الخطافان معًا تجربة نموذج كاملة وسهلة الوصول.