useActionState()

إدارة حالة نموذج مبنية على Action useActionState()

useActionState يربط حالة بنتيجة تنفيذ دالة غير متزامنة (Action)، مع إدارة تلقائية لحالة "جارٍ التنفيذ" — مثالي لنماذج <form>.

useActionState(action, initialState, permalink?) يُرجع [state, formAction, isPending]. الدالة action تستقبل (previousState, formData) وتُرجع الحالة التالية؛ يبدأ state بقيمة initialState ثم يساوي آخر ما أرجعته action.

تمرير formAction مباشرة إلى <form action={formAction}> يجعل React يغلّف الإرسال تلقائيًا داخل Transition، فتتوفّر isPending جاهزة بلا كتابة startTransition يدويًا، وتُنفَّذ عدة استدعاءات متتالية بالترتيب.

الصياغة

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

async function action(previousState, formData) {
  // ...
  return newState;
}

📄 مثال

async function submitName(previousState, formData) {
  const name = formData.get("name");
  if (!name) return { error: "الاسم مطلوب" };
  await saveName(name);
  return { error: null };
}

function NameForm() {
  const [state, formAction, isPending] = useActionState(submitName, { error: null });
  return (
    <form action={formAction}>
      <input name="name" />
      {state.error && <p>{state.error}</p>}
      <button disabled={isPending}>{isPending ? "..." : "حفظ"}</button>
    </form>
  );
}

أهم المعاملات

المعامل	الوظيفة
action	دالة (previousState, formData) => newState، يمكن أن تكون async
initialState	القيمة الابتدائية — تُتجاهَل بعد أول تنفيذ لـ action
permalink	رابط اختياري يُستخدَم مع مكوّنات الخادم للتحسين التدريجي (progressive enhancement)

💡 نصائح عملية

لا حاجة لـ e.preventDefault() ولا useState منفصل لكل حقل — formData تصل جاهزة لدالة action
استخدم useFormStatus من react-dom في مكوّن فرعي داخل <form> لقراءة حالة الإرسال دون تمرير isPending يدويًا

⚠️ أخطاء شائعة

استدعاء formAction خارج سياق نموذج أو Transition بلا تغليفها بـ startTransition يدويًا
توقّع تحديث initialState لاحقًا — بعد أول استدعاء لـ action تُتجاهَل initialState كليًا ويُعتمَد فقط على القيمة المُرجَعة

🎓 تريد فهم الصورة الكاملة خطوة بخطوة؟ ابدأ من مسار REACT الكامل بالعربي.