React useFormStatus: دليل شامل لإدارة حالة النماذج

يقدم الخطاف useFormStatus، الذي تم تقديمه في React 18، طريقة قوية وفعالة لإدارة حالة إرسال النماذج ضمن مكونات خادم React. تم تصميم هذا الخطاف خصيصًا للعمل مع إجراءات الخادم (Server Actions)، مما يوفر تكاملاً سلسًا لمعالجة عمليات إرسال النماذج مباشرة على الخادم. إنه يبسط عملية تتبع حالة إرسال النموذج، ويوفر معلومات قيمة مثل ما إذا كان النموذج معلقًا، أو نجح، أو واجه خطأ. يستكشف هذا الدليل إمكانيات useFormStatus، وفوائده، وأمثلة عملية توضح استخدامه في سيناريوهات مختلفة.

فهم إجراءات الخادم و useFormStatus

قبل الغوص في useFormStatus، من الضروري فهم مكونات خادم React وإجراءات الخادم. تسمح لك إجراءات الخادم بتحديد وظائف تعمل على الخادم، ويمكن الوصول إليها مباشرة من مكونات React الخاصة بك. وهذا يتيح معالجة عمليات إرسال النماذج، وجلب البيانات، والعمليات الأخرى من جانب الخادم دون الحاجة إلى نقطة نهاية API منفصلة.

يوفر الخطاف useFormStatus بعد ذلك رؤى حول تنفيذ إجراءات الخادم هذه التي يتم تشغيلها عن طريق إرسال النماذج.

ما هو useFormStatus؟

useFormStatus هو خطاف React يعيد كائنًا يحتوي على معلومات حول حالة آخر عملية إرسال للنموذج. تتضمن هذه المعلومات:

• pending: قيمة منطقية (boolean) تشير إلى ما إذا كان النموذج قيد الإرسال حاليًا.
• data: كائن FormData المرتبط بعملية الإرسال.
• method: طريقة HTTP المستخدمة للإرسال (عادةً 'POST').
• action: دالة إجراء الخادم (Server Action) التي تم تشغيلها.

فوائد استخدام useFormStatus

يقدم استخدام useFormStatus العديد من المزايا الرئيسية:

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

أمثلة عملية على useFormStatus

دعنا نستكشف عدة أمثلة عملية لتوضيح استخدام useFormStatus في سيناريوهات مختلفة.

إرسال نموذج أساسي مع مؤشر تحميل

يوضح هذا المثال نموذجًا بسيطًا مع مؤشر تحميل يتم عرضه أثناء إرسال النموذج.

إجراء الخادم (actions.js):

'use server'

export async function submitForm(formData) {
  // Simulate a delay to demonstrate the loading state
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');
  console.log('Form submitted with name:', name);
  return { message: `Form submitted successfully with name: ${name}` };
}

مكون React (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'

function FormComponent() {
  const { pending } = useFormStatus()

  return (
    

      الاسم:
      
      
        {pending ? 'جارٍ الإرسال...' : 'إرسال'}
      
    
  )
}

export default FormComponent

في هذا المثال، يتم استخدام خاصية pending من useFormStatus لتعطيل حقل الإدخال والزر أثناء إرسال النموذج، ولعرض رسالة "جارٍ الإرسال...".

معالجة حالات النجاح والخطأ

يوضح هذا المثال كيفية معالجة حالات النجاح والخطأ بعد إرسال النموذج.

إجراء الخادم (actions.js):

'use server'

export async function submitForm(formData) {
  // Simulate a delay
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');

  if (!name) {
    throw new Error('Name is required');
  }

  console.log('Form submitted with name:', name);
  return { message: `Form submitted successfully with name: ${name}` };
}

مكون React (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await submitForm(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      الاسم:
      
      
        {pending ? 'جارٍ الإرسال...' : 'إرسال'}
      
      {pending && 
جارٍ الإرسال...
}
      {message && 
{message}
}
      {error && 
خطأ: {error}
}
    
  )
}

export default FormComponent

في هذا المثال، يتم استخدام كتلة try/catch في دالة handleSubmit. إذا أطلق إجراء الخادم خطأ، يتم التقاطه وعرضه للمستخدم. يتم عرض رسالة نجاح عند الإرسال الناجح.

استخدام FormData للبيانات المعقدة

يعمل useFormStatus بسلاسة مع FormData، مما يسمح لك بمعالجة هياكل البيانات المعقدة بسهولة. إليك مثال يوضح كيفية رفع الملفات.

إجراء الخادم (actions.js):

'use server'

export async function uploadFile(formData) {
  // Simulate file processing
  await new Promise(resolve => setTimeout(resolve, 2000));

  const file = formData.get('file');

  if (!file) {
    throw new Error('No file uploaded');
  }

  console.log('File uploaded:', file.name);
  return { message: `File uploaded successfully: ${file.name}` };
}

مكون React (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { uploadFile } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await uploadFile(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      رفع ملف:
      
      
        {pending ? 'جارٍ الرفع...' : 'رفع'}
      
      {pending && 
جارٍ الرفع...
}
      {message && 
{message}
}
      {error && 
خطأ: {error}
}
    
  )
}

export default FormComponent

يوضح هذا المثال كيفية معالجة عمليات رفع الملفات باستخدام FormData. يسترجع إجراء الخادم الملف من كائن FormData ويعالجه. يدير الخطاف useFormStatus حالة التحميل أثناء رفع الملف.

أفضل الممارسات لاستخدام useFormStatus

لتحقيق أقصى استفادة من useFormStatus، ضع في اعتبارك هذه الممارسات الأفضل:

• توفير ملاحظات واضحة للمستخدم: استخدم حالة pending لعرض مؤشرات تحميل إعلامية وتعطيل عناصر النموذج لمنع عمليات الإرسال المتعددة.
• معالجة الأخطاء بأمان: قم بتنفيذ معالجة الأخطاء لالتقاط الاستثناءات في إجراءات الخادم الخاصة بك وعرض رسائل خطأ سهلة الفهم للمستخدم.
• التحقق من صحة البيانات على الخادم: قم بإجراء التحقق من الصحة من جانب الخادم لضمان سلامة البيانات وأمانها.
• إبقاء إجراءات الخادم موجزة: ركز إجراءات الخادم على مهام محددة لتحسين الأداء وقابلية الصيانة.
• مراعاة إمكانية الوصول: تأكد من أن نماذجك قابلة للوصول من خلال توفير تسميات مناسبة وسمات ARIA ودعم التنقل باستخدام لوحة المفاتيح.

حالات الاستخدام المتقدمة

بالإضافة إلى الأمثلة الأساسية، يمكن استخدام useFormStatus في سيناريوهات أكثر تعقيدًا:

• التحسين التدريجي: استخدم إجراءات الخادم و useFormStatus لتحسين نماذجك تدريجيًا، مما يوفر تجربة أساسية للمستخدمين الذين قاموا بتعطيل JavaScript وتجربة أغنى لأولئك الذين لديهم JavaScript ممكّن.
• التحديثات المتفائلة: قم بتنفيذ تحديثات متفائلة عن طريق تحديث واجهة المستخدم فور إرسال النموذج، بافتراض أن الإرسال سينجح. قم بالتراجع عن التحديث إذا فشل الإرسال.
• التكامل مع مكتبات النماذج: قم بدمج useFormStatus مع مكتبات النماذج الشائعة مثل Formik أو React Hook Form لإدارة حالة النموذج والتحقق من صحته. على الرغم من أن هذه المكتبات غالبًا ما يكون لديها إدارة حالة خاصة بها، إلا أن useFormStatus يمكن أن يكون مفيدًا لمرحلة الإرسال النهائية إلى إجراء الخادم.

اعتبارات التدويل (i18n)

عند بناء نماذج لجمهور عالمي، يعد التدويل (i18n) أمرًا بالغ الأهمية. إليك كيفية مراعاة i18n عند استخدام useFormStatus:

• رسائل الخطأ المترجمة: تأكد من أن رسائل الخطأ المعروضة للمستخدم مترجمة إلى لغتهم المفضلة. يمكن تحقيق ذلك عن طريق تخزين رسائل الخطأ في ملفات الترجمة واستخدام مكتبة مثل react-intl أو i18next لاسترداد الترجمة المناسبة.
• تنسيق التاريخ والأرقام: تعامل مع تنسيق التاريخ والأرقام وفقًا للغة المستخدم. استخدم مكتبات مثل Intl.DateTimeFormat و Intl.NumberFormat لتنسيق هذه القيم بشكل صحيح.
• دعم من اليمين إلى اليسار (RTL): إذا كان تطبيقك يدعم اللغات التي تُكتب من اليمين إلى اليسار (مثل العربية والعبرية)، فتأكد من أن نماذجك مصممة بشكل صحيح لاستيعاب تخطيطات RTL.
• التحقق من صحة النموذج: قم بتخصيص قواعد التحقق من صحة النموذج لتناسب اللغات المختلفة. على سبيل المثال، قد يختلف التحقق من صحة رقم الهاتف بشكل كبير بين البلدان.

مثال على رسائل الخطأ المترجمة:

// translations/ar.json
{
  "form.error.nameRequired": "يرجى إدخال اسمك.",
  "form.success.submission": "شكرا لك على إرسالك!"
}

// translations/fr.json
{
  "form.error.nameRequired": "Veuillez entrer votre nom.",
  "form.success.submission": "Merci pour votre soumission !"
}

// Component using react-intl
import { useIntl } from 'react-intl';

function FormComponent() {
  const intl = useIntl();
  const [error, setError] = useState(null);

  // ...

  catch (e) {
    setError(intl.formatMessage({ id: 'form.error.nameRequired' }));
  }
}

اعتبارات إمكانية الوصول

تعد إمكانية الوصول جانبًا رئيسيًا لبناء تطبيقات ويب شاملة. إليك العديد من اعتبارات إمكانية الوصول التي يجب وضعها في الاعتبار عند استخدام useFormStatus:

• سمات ARIA: استخدم سمات ARIA لتزويد التقنيات المساعدة بمعلومات حول حالة النموذج. على سبيل المثال، استخدم aria-busy="true" على زر الإرسال أثناء تعليق النموذج.
• التسميات: تأكد من أن جميع حقول النموذج لها تسميات واضحة ووصفية مرتبطة بعناصر الإدخال باستخدام عنصر <label>.
• رسائل الخطأ: اعرض رسائل الخطأ بطريقة يسهل ملاحظتها وفهمها من قبل المستخدمين ذوي الإعاقة. استخدم سمات ARIA مثل aria-live="assertive" لإعلان رسائل الخطأ لقارئات الشاشة.
• التنقل باستخدام لوحة المفاتيح: تأكد من أن المستخدمين يمكنهم التنقل في النموذج باستخدام لوحة المفاتيح وحدها. استخدم السمة tabindex للتحكم في الترتيب الذي تتلقى به العناصر التركيز.
• تباين الألوان: تأكد من أن ألوان النص والخلفية المستخدمة في النموذج بها تباين كافٍ لتكون سهلة القراءة من قبل المستخدمين الذين يعانون من إعاقات بصرية.

useFormStatus مقابل إدارة الحالة التقليدية

تقليديًا، قام مطورو React بإدارة حالة إرسال النموذج باستخدام حالة المكون (useState) أو مكتبات إدارة الحالة الأكثر تعقيدًا (مثل Redux، Zustand). إليك مقارنة بين هذه الأساليب و useFormStatus:

الميزة	useFormStatus	useState	إدارة الحالة الخارجية
التعقيد	منخفض	متوسط	مرتفع
التكامل مع إجراءات الخادم	سلس	يتطلب تكاملاً يدويًا	يتطلب تكاملاً يدويًا
الكود المتكرر (Boilerplate)	ضئيل	معتدل	كبير
حالات الاستخدام المناسبة	النماذج التي تُرسل مباشرة إلى إجراءات الخادم	نماذج بسيطة بحالة محدودة	نماذج معقدة بحالة مشتركة عبر المكونات

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

استكشاف الأخطاء الشائعة وإصلاحها

إليك بعض المشكلات الشائعة التي قد تواجهها عند استخدام useFormStatus وكيفية استكشافها وإصلاحها:

• useFormStatus لا يتم تحديثه:
  • تأكد من أنك تستخدم useFormStatus داخل عنصر <form> الذي تم تعيين خاصية action الخاصة به إلى إجراء خادم.
  • تحقق من أن إجراء الخادم محدد ومُصدَّر بشكل صحيح.
  • تحقق من وجود أي أخطاء في إجراء الخادم قد تمنعه من الإكمال بنجاح.
• رسائل الخطأ لا تظهر:
  • تأكد من أنك تلتقط الأخطاء بشكل صحيح في إجراء الخادم الخاص بك وتعيد رسالة خطأ.
  • تحقق من أنك تعرض رسالة الخطأ في مكونك باستخدام حالة error.
• مؤشر التحميل لا يظهر:
  • تأكد من أنك تستخدم حالة pending من useFormStatus لعرض مؤشر التحميل بشكل شرطي.
  • تحقق من أن إجراء الخادم يستغرق بالفعل بعض الوقت ليكتمل (على سبيل المثال، عن طريق محاكاة تأخير).

الخاتمة

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