React useFormStatus: راهنمای جامع برای مدیریت وضعیت فرم

هوک useFormStatus که در React 18 معرفی شد، روشی قدرتمند و کارآمد برای مدیریت وضعیت ارسال فرم‌ها در کامپوننت‌های سرور ری‌اکت (React Server Components) فراهم می‌کند. این هوک به طور خاص برای کار با اکشن‌های سرور (Server Actions) طراحی شده است و یکپارچگی بی‌نقصی را برای مدیریت ارسال فرم‌ها مستقیماً روی سرور ارائه می‌دهد. این هوک فرآیند پیگیری وضعیت ارسال فرم را ساده می‌کند و اطلاعات ارزشمندی مانند اینکه آیا فرم در حالت انتظار (pending) است، با موفقیت ارسال شده یا با خطا مواجه شده است را فراهم می‌کند. این راهنما به بررسی قابلیت‌های useFormStatus، مزایای آن و مثال‌های عملی برای نشان دادن کاربرد آن در سناریوهای مختلف می‌پردازد.

آشنایی با Server Actions و useFormStatus

قبل از پرداختن به useFormStatus، درک کامپوننت‌های سرور ری‌اکت و اکشن‌های سرور بسیار مهم است. اکشن‌های سرور به شما این امکان را می‌دهند که توابعی را تعریف کنید که روی سرور اجرا می‌شوند و مستقیماً از کامپوننت‌های ری‌اکت شما قابل دسترسی هستند. این قابلیت، مدیریت ارسال فرم‌ها، واکشی داده‌ها و سایر عملیات سمت سرور را بدون نیاز به یک API endpoint جداگانه امکان‌پذیر می‌سازد.

سپس هوک useFormStatus اطلاعاتی در مورد اجرای این اکشن‌های سرور که توسط ارسال فرم‌ها فعال می‌شوند، فراهم می‌کند.

useFormStatus چیست؟

useFormStatus یک هوک ری‌اکت است که یک شیء حاوی اطلاعات مربوط به وضعیت آخرین ارسال فرم را برمی‌گرداند. این اطلاعات شامل موارد زیر است:

• pending: یک مقدار بولین (boolean) که نشان می‌دهد آیا فرم در حال حاضر در حال ارسال است یا خیر.
• data: شیء FormData مرتبط با ارسال.
• method: متد HTTP استفاده شده برای ارسال (معمولاً 'POST').
• action: تابع اکشن سرور (Server Action) که فراخوانی شده است.

مزایای استفاده از useFormStatus

استفاده از useFormStatus چندین مزیت کلیدی دارد:

• مدیریت وضعیت ساده‌شده: نیاز به مدیریت دستی وضعیت برای پیگیری وضعیت ارسال فرم را از بین می‌برد. این هوک به طور خودکار با پیشرفت ارسال، به‌روزرسانی می‌شود.
• بهبود تجربه کاربری: بازخورد آنی به کاربران ارائه می‌دهد، مانند نمایش نشانگرهای بارگذاری در حین پردازش فرم یا نمایش پیام‌های خطا در صورت شکست.
• کد تمیز: با جدا کردن منطق ارسال فرم از رندر کامپوننت، به یک پایگاه کد خواناتر و قابل نگهداری‌تر کمک می‌کند.
• یکپارچگی بی‌نقص با اکشن‌های سرور: برای کار بی‌نقص با اکشن‌های سرور طراحی شده است و مدیریت ارسال فرم‌ها را مستقیماً روی سرور آسان می‌کند.

مثال‌های عملی از useFormStatus

بیایید چندین مثال عملی را برای نشان دادن کاربرد useFormStatus در سناریوهای مختلف بررسی کنیم.

ارسال فرم پایه با نشانگر بارگذاری

این مثال یک فرم ساده با یک نشانگر بارگذاری را نشان می‌دهد که در حین ارسال فرم نمایش داده می‌شود.

اکشن سرور (actions.js):

'use server'

export async function submitForm(formData) {
  // شبیه‌سازی یک تأخیر برای نمایش حالت بارگذاری
  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}` };
}

کامپوننت ری‌اکت (FormComponent.jsx):

'use client'

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

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

  return (
    

      Name:
      
      
        {pending ? 'Submitting...' : 'Submit'}
      
    
  )
}

export default FormComponent

در این مثال، ویژگی pending از useFormStatus برای غیرفعال کردن فیلد ورودی و دکمه در حین ارسال فرم و همچنین برای نمایش پیام "...در حال ارسال" استفاده می‌شود.

مدیریت وضعیت‌های موفقیت و خطا

این مثال نحوه مدیریت وضعیت‌های موفقیت و خطا پس از ارسال فرم را نشان می‌دهد.

اکشن سرور (actions.js):

'use server'

export async function submitForm(formData) {
  // شبیه‌سازی یک تأخیر
  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}` };
}

کامپوننت ری‌اکت (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 (
    

      Name:
      
      
        {pending ? 'Submitting...' : 'Submit'}
      
      {pending && 
Submitting...
}
      {message && 
{message}
}
      {error && 
Error: {error}
}
    
  )
}

export default FormComponent

در این مثال، یک بلوک try/catch در تابع handleSubmit استفاده شده است. اگر اکشن سرور یک خطا پرتاب کند، آن خطا گرفته شده و به کاربر نمایش داده می‌شود. یک پیام موفقیت پس از ارسال موفق نمایش داده می‌شود.

استفاده از FormData برای داده‌های پیچیده

useFormStatus به طور بی‌نقص با FormData کار می‌کند و به شما امکان می‌دهد ساختارهای داده پیچیده را به راحتی مدیریت کنید. در اینجا مثالی برای آپلود فایل آورده شده است.

اکشن سرور (actions.js):

'use server'

export async function uploadFile(formData) {
  // شبیه‌سازی پردازش فایل
  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}` };
}

کامپوننت ری‌اکت (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 (
    

      Upload File:
      
      
        {pending ? 'Uploading...' : 'Upload'}
      
      {pending && 
Uploading...
}
      {message && 
{message}
}
      {error && 
Error: {error}
}
    
  )
}

export default FormComponent

این مثال نحوه مدیریت آپلود فایل با استفاده از FormData را نشان می‌دهد. اکشن سرور فایل را از شیء FormData دریافت کرده و آن را پردازش می‌کند. هوک useFormStatus وضعیت بارگذاری را در حین آپلود فایل مدیریت می‌کند.

بهترین شیوه‌ها برای استفاده از useFormStatus

برای به حداکثر رساندن مزایای useFormStatus، این بهترین شیوه‌ها را در نظر بگیرید:

• ارائه بازخورد واضح به کاربر: از وضعیت pending برای نمایش نشانگرهای بارگذاری آموزنده و غیرفعال کردن عناصر فرم برای جلوگیری از ارسال‌های متعدد استفاده کنید.
• مدیریت خطاها به صورت زیبا: مدیریت خطا را برای گرفتن استثناها در اکشن‌های سرور خود پیاده‌سازی کرده و پیام‌های خطای کاربرپسند نمایش دهید.
• اعتبارسنجی داده‌ها روی سرور: اعتبارسنجی سمت سرور را برای اطمینان از یکپارچگی و امنیت داده‌ها انجام دهید.
• کوتاه نگه داشتن اکشن‌های سرور: اکشن‌های سرور را بر روی وظایف خاص متمرکز کنید تا عملکرد و قابلیت نگهداری بهبود یابد.
• در نظر گرفتن دسترسی‌پذیری: با ارائه برچسب‌های مناسب، ویژگی‌های ARIA و پشتیبانی از ناوبری با صفحه‌کلید، از دسترسی‌پذیر بودن فرم‌های خود اطمینان حاصل کنید.

موارد استفاده پیشرفته

علاوه بر مثال‌های پایه، useFormStatus می‌تواند در سناریوهای پیچیده‌تر نیز استفاده شود:

• بهبود تدریجی (Progressive Enhancement): از اکشن‌های سرور و useFormStatus برای بهبود تدریجی فرم‌های خود استفاده کنید، به طوری که یک تجربه پایه برای کاربرانی که جاوااسکریپت غیرفعال دارند و یک تجربه غنی‌تر برای کسانی که جاوااسکریپت فعال دارند، فراهم شود.
• به‌روزرسانی‌های خوش‌بینانه (Optimistic Updates): به‌روزرسانی‌های خوش‌بینانه را با به‌روزرسانی فوری UI پس از ارسال فرم پیاده‌سازی کنید، با این فرض که ارسال موفقیت‌آمیز خواهد بود. در صورت شکست ارسال، به‌روزرسانی را برگردانید.
• ادغام با کتابخانه‌های فرم: useFormStatus را با کتابخانه‌های محبوب فرم مانند Formik یا React Hook Form برای مدیریت وضعیت و اعتبارسنجی فرم ادغام کنید. در حالی که این کتابخانه‌ها اغلب مدیریت وضعیت خود را دارند، useFormStatus می‌تواند برای مرحله نهایی ارسال به یک اکشن سرور مفید باشد.

ملاحظات برای بین‌المللی‌سازی (i18n)

هنگام ساخت فرم برای مخاطبان جهانی، بین‌المللی‌سازی (i18n) بسیار مهم است. در اینجا نحوه در نظر گرفتن i18n هنگام استفاده از useFormStatus آورده شده است:

• پیام‌های خطای محلی‌سازی شده: اطمینان حاصل کنید که پیام‌های خطای نمایش داده شده به کاربر به زبان ترجیحی آنها محلی‌سازی شده‌اند. این کار را می‌توان با ذخیره پیام‌های خطا در فایل‌های ترجمه و استفاده از کتابخانه‌ای مانند react-intl یا i18next برای بازیابی ترجمه مناسب انجام داد.
• قالب‌بندی تاریخ و شماره: قالب‌بندی تاریخ و شماره را مطابق با منطقه کاربر انجام دهید. از کتابخانه‌هایی مانند Intl.DateTimeFormat و Intl.NumberFormat برای قالب‌بندی صحیح این مقادیر استفاده کنید.
• پشتیبانی از راست به چپ (RTL): اگر برنامه شما از زبان‌هایی که از راست به چپ نوشته می‌شوند (مانند عربی، عبری) پشتیبانی می‌کند، اطمینان حاصل کنید که فرم‌های شما به درستی برای چیدمان‌های RTL استایل‌دهی شده‌اند.
• اعتبارسنجی فرم: قوانین اعتبارسنجی فرم را برای مناطق مختلف تنظیم کنید. به عنوان مثال، اعتبارسنجی شماره تلفن ممکن است در کشورهای مختلف بسیار متفاوت باشد.

مثالی از پیام‌های خطای محلی‌سازی شده:

// translations/en.json
{
  "form.error.nameRequired": "Please enter your name.",
  "form.success.submission": "Thank you for your submission!"
}

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

// کامپوننت با استفاده از 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 در مقابل مدیریت وضعیت سنتی

به طور سنتی، توسعه‌دهندگان ری‌اکت وضعیت ارسال فرم را با استفاده از وضعیت کامپوننت (useState) یا کتابخانه‌های مدیریت وضعیت پیچیده‌تر (مانند Redux، Zustand) مدیریت می‌کردند. در اینجا مقایسه‌ای بین این رویکردها و useFormStatus آورده شده است:

ویژگی	useFormStatus	useState	مدیریت وضعیت خارجی
پیچیدگی	کم	متوسط	زیاد
یکپارچگی با اکشن‌های سرور	بی‌نقص	نیاز به یکپارچه‌سازی دستی دارد	نیاز به یکپارچه‌سازی دستی دارد
کد تکراری (Boilerplate)	حداقل	متوسط	قابل توجه
موارد استفاده مناسب	فرم‌هایی که مستقیماً به اکشن‌های سرور ارسال می‌شوند	فرم‌های ساده با وضعیت محدود	فرم‌های پیچیده با وضعیت مشترک بین کامپوننت‌ها

useFormStatus زمانی می‌درخشد که فرم‌های شما مستقیماً با اکشن‌های سرور ری‌اکت در تعامل هستند. این هوک کد تکراری را کاهش داده و فرآیند را ساده می‌کند. با این حال، برای فرم‌های بسیار پیچیده با وضعیتی که بین چندین کامپوننت به اشتراک گذاشته شده است، یک کتابخانه مدیریت وضعیت کامل ممکن است همچنان ضروری باشد.

عیب‌یابی مشکلات رایج

در اینجا برخی از مشکلات رایجی که ممکن است هنگام استفاده از useFormStatus با آنها مواجه شوید و نحوه عیب‌یابی آنها آورده شده است:

• useFormStatus به‌روزرسانی نمی‌شود:
  • اطمینان حاصل کنید که از useFormStatus در داخل یک عنصر <form> استفاده می‌کنید که پراپ action آن به یک اکشن سرور تنظیم شده است.
  • بررسی کنید که اکشن سرور به درستی تعریف و صادر (export) شده باشد.
  • هرگونه خطایی در اکشن سرور را که ممکن است از تکمیل موفقیت‌آمیز آن جلوگیری کند، بررسی کنید.
• پیام‌های خطا نمایش داده نمی‌شوند:
  • مطمئن شوید که خطاها را به درستی در اکشن سرور خود می‌گیرید و یک پیام خطا برمی‌گردانید.
  • بررسی کنید که پیام خطا را با استفاده از وضعیت error در کامپوننت خود نمایش می‌دهید.
• نشانگر بارگذاری ظاهر نمی‌شود:
  • اطمینان حاصل کنید که از وضعیت pending از useFormStatus برای نمایش شرطی نشانگر بارگذاری استفاده می‌کنید.
  • بررسی کنید که اکشن سرور واقعاً مدتی طول می‌کشد تا کامل شود (مثلاً با شبیه‌سازی یک تأخیر).

نتیجه‌گیری

useFormStatus یک روش تمیز و کارآمد برای مدیریت وضعیت ارسال فرم در برنامه‌های ری‌اکت با استفاده از کامپوننت‌های سرور فراهم می‌کند. با بهره‌گیری از این هوک، می‌توانید کد خود را ساده‌تر کنید، تجربه کاربری را بهبود بخشید و به طور بی‌نقص با اکشن‌های سرور یکپارچه شوید. این راهنما اصول اولیه useFormStatus را پوشش داد، مثال‌های عملی ارائه کرد و بهترین شیوه‌ها برای استفاده مؤثر از آن را مورد بحث قرار داد. با گنجاندن useFormStatus در پروژه‌های ری‌اکت خود، می‌توانید مدیریت فرم خود را ساده‌تر کرده و برنامه‌های قوی‌تر و کاربرپسندتری برای مخاطبان جهانی بسازید.