React experimental_useFormStatus: یک راهنمای جامع

اکوسیستم در حال تحول React به طور مداوم ابزارها و APIهای جدیدی را برای بهبود تجربه توسعه‌دهندگان و عملکرد برنامه‌ها معرفی می‌کند. یکی از این افزوده‌ها که در حال حاضر در مرحله آزمایشی قرار دارد، هوک experimental_useFormStatus است. این هوک اطلاعات ارزشمندی در مورد وضعیت ارسال فرم، به ویژه هنگام کار با سرور اکشن‌ها (server actions)، ارائه می‌دهد. این راهنما به جزئیات experimental_useFormStatus می‌پردازد و عملکرد، مزایا و کاربردهای عملی آن را بررسی می‌کند.

هوک experimental_useFormStatus چیست؟

هوک experimental_useFormStatus برای ارائه اطلاعات در مورد وضعیت ارسال فرمی که با استفاده از React Server Actions آغاز شده، طراحی شده است. این هوک به کامپوننت‌ها اجازه می‌دهد تا به مراحل مختلف فرآیند ارسال فرم، مانند در حال انتظار (pending)، موفقیت‌آمیز (success) یا ناموفق (failure)، واکنش نشان دهند. این امر به توسعه‌دهندگان امکان می‌دهد تا تجربیات کاربری فرم پاسخ‌گوتر و کاربرپسندتری ایجاد کنند.

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

مزایای کلیدی استفاده از experimental_useFormStatus

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

درک ساختار experimental_useFormStatus

هوک experimental_useFormStatus یک شیء حاوی چندین ویژگی کلیدی را برمی‌گرداند. این ویژگی‌ها اطلاعات ارزشمندی در مورد وضعیت فعلی ارسال فرم ارائه می‌دهند. بیایید هر ویژگی را با جزئیات بررسی کنیم:

• pending: یک مقدار بولین (boolean) که نشان می‌دهد آیا ارسال فرم در حال حاضر در حال انجام است یا خیر. این برای نمایش یک نشانگر بارگذاری مفید است.
• data: داده‌های بازگشتی از سرور اکشن پس از ارسال موفقیت‌آمیز فرم. این می‌تواند برای به‌روزرسانی UI با نتایج اکشن استفاده شود.
• error: یک شیء خطا حاوی اطلاعات در مورد هر خطایی که در حین ارسال فرم رخ داده است. این می‌تواند برای نمایش پیام‌های خطا به کاربر استفاده شود.
• action: تابع سرور اکشن که برای ارسال فرم استفاده شده است. این می‌تواند برای فعال کردن مجدد اکشن در صورت لزوم مفید باشد.
• formState: وضعیت فرم قبل از ارسال. این یک تصویر لحظه‌ای (snapshot) از داده‌هایی که فرم قبل از شروع فرآیند ارسال در خود نگه داشته بود، ارائه می‌دهد.

مثال استفاده پایه

در اینجا یک مثال پایه از نحوه استفاده از experimental_useFormStatus در یک کامپوننت React آورده شده است:

import { experimental_useFormStatus as useFormStatus } from 'react-dom';

async function myAction(formData) {
  'use server'
  // منطق سمت سرور را اینجا انجام دهید
  await new Promise(resolve => setTimeout(resolve, 2000)); // شبیه‌سازی یک تأخیر

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

  if (!name) {
    return { message: 'Name is required.' };
  }

  return { message: `Hello, ${name}!` };
}

function MyForm() {
  const { pending, data, error } = useFormStatus();

  return (
    

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

export default MyForm;

در این مثال، useFormStatus برای پیگیری وضعیت ارسال فرم که توسط سرور اکشن myAction آغاز شده، استفاده می‌شود. ویژگی pending برای غیرفعال کردن ورودی و دکمه در حین ارسال استفاده می‌شود، در حالی که ویژگی‌های data و error به ترتیب برای نمایش پیام‌های موفقیت و خطا استفاده می‌شوند.

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

فراتر از پیگیری پایه ارسال فرم، experimental_useFormStatus می‌تواند در سناریوهای پیشرفته‌تری نیز استفاده شود. در اینجا چند مثال آورده شده است:

۱. به‌روزرسانی‌های خوش‌بینانه (Optimistic Updates)

به‌روزرسانی‌های خوش‌بینانه شامل به‌روزرسانی فوری UI بلافاصله پس از ارسال فرم توسط کاربر است، با این فرض که ارسال موفقیت‌آمیز خواهد بود. این کار می‌تواند عملکرد درک شده برنامه را بهبود بخشد. experimental_useFormStatus می‌تواند برای بازگرداندن به‌روزرسانی خوش‌بینانه در صورت شکست ارسال فرم استفاده شود.

import { experimental_useFormStatus as useFormStatus } from 'react-dom';
import { useState } from 'react';

async function updateProfile(formData) {
  'use server'
  // شبیه‌سازی یک تأخیر
  await new Promise(resolve => setTimeout(resolve, 2000));

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

  if (!name) {
    return { success: false, message: 'Name is required.' };
  }

  return { success: true, message: `Profile updated for ${name}!` };
}

function ProfileForm({ initialName }) {
  const { pending, data, error } = useFormStatus();
  const [name, setName] = useState(initialName);

  const handleSubmit = async (e) => {
      e.preventDefault();

      // به‌روزرسانی خوش‌بینانه
      setName(e.target.name.value);

      const formData = new FormData(e.target);
      const result = await updateProfile(formData);

      if (result && !result.success) {
          // بازگرداندن به‌روزرسانی خوش‌بینانه در صورت شکست ارسال
          setName(initialName); // بازگشت به مقدار اصلی
      }
  };

  return (
    

      Name:
       setName(e.target.value)} disabled={pending} />
      
        {pending ? 'Updating...' : 'Update Profile'}
      
      {error && 
Error: {error.message}
}
      {data && data.success && 
{data.message}
}
    
  );
}

export default ProfileForm;

۲. رندر شرطی (Conditional Rendering)

experimental_useFormStatus می‌تواند برای رندر شرطی عناصر مختلف UI بر اساس وضعیت ارسال فرم استفاده شود. به عنوان مثال، می‌توانید بر اساس بازگشتی سرور اکشن، پیام یا UI متفاوتی نمایش دهید.

import { experimental_useFormStatus as useFormStatus } from 'react-dom';

async function processOrder(formData) {
  'use server'
  // شبیه‌سازی یک تأخیر
  await new Promise(resolve => setTimeout(resolve, 2000));

  const orderId = Math.floor(Math.random() * 1000);

  return { orderId };
}

function OrderForm() {
  const { pending, data, error } = useFormStatus();

  return (
    

      
        {pending ? 'Processing Order...' : 'Place Order'}
      
      {error && 
Error: {error.message}
}
      {data && data.orderId && (
        

          
Order placed successfully!
          
Your order ID is: {data.orderId}
        
      )}
      {!pending && !data && !error && 
Ready to place your order.
}
    
  );
}

export default OrderForm;

۳. ملاحظات دسترسی‌پذیری

دسترسی‌پذیری در توسعه وب امری حیاتی است. با experimental_useFormStatus، می‌توانید دسترسی‌پذیری فرم را به میزان قابل توجهی افزایش دهید. به عنوان مثال، می‌توانید از ویژگی‌های ARIA برای اطلاع‌رسانی به صفحه‌خوان‌ها در مورد وضعیت ارسال فرم استفاده کنید.

import { experimental_useFormStatus as useFormStatus } from 'react-dom';

async function submitComment(formData) {
  'use server'
  await new Promise(resolve => setTimeout(resolve, 2000));

  const commentText = formData.get('comment');

  if (!commentText) {
    return { message: 'Comment is required.' };
  }

  return { message: 'Comment submitted successfully!' };
}

function CommentForm() {
  const { pending, data, error } = useFormStatus();

  return (
    

      Comment:
      
      
        {pending ? 'Submitting...' : 'Submit Comment'}
      
      {error && 
Error: {error.message}
}
      {data && 
{data.message}
}
    
  );
}

export default CommentForm;

در این قطعه کد، aria-busy={pending} به فناوری‌های کمکی اطلاع می‌دهد که فرم در حال ارسال است، و role="alert" و role="status" به ترتیب پیام‌های خطا و موفقیت را به درستی برچسب‌گذاری می‌کنند.

ملاحظات جهانی و بهترین شیوه‌ها

هنگام توسعه فرم‌ها برای مخاطبان جهانی با استفاده از experimental_useFormStatus، چندین ملاحظه باید در نظر گرفته شود تا تجربه کاربری یکپارچه‌ای تضمین شود:

• بومی‌سازی (Localization): اطمینان حاصل کنید که تمام پیام‌های خطا و موفقیت به درستی برای زبان‌های مختلف بومی‌سازی شده‌اند. این شامل ترجمه خود پیام‌ها و همچنین تطبیق فرمت پیام با قراردادهای هر زبان است. استفاده از کتابخانه‌هایی مانند i18next یا Context API داخلی React را برای مدیریت ترجمه‌ها در نظر بگیرید.
• فرمت‌های تاریخ و زمان: به فرمت‌های مختلف تاریخ و زمان که در سراسر جهان استفاده می‌شوند، توجه داشته باشید. از کتابخانه‌ای مانند date-fns یا moment.js برای فرمت‌بندی مناسب تاریخ‌ها و زمان‌ها برای هر منطقه استفاده کنید. به عنوان مثال، در آمریکا از MM/DD/YYYY استفاده می‌شود، در حالی که بسیاری از کشورهای اروپایی از DD/MM/YYYY استفاده می‌کنند.
• فرمت‌های عددی: به طور مشابه، فرمت‌های اعداد در مناطق مختلف متفاوت است. از API Intl.NumberFormat برای فرمت‌بندی اعداد مطابق با منطقه کاربر استفاده کنید. این شامل مدیریت جداکننده‌های اعشاری، جداکننده‌های هزارگان و نمادهای ارز است.
• مدیریت ارز: اگر فرم شما شامل تراکنش‌های مالی است، اطمینان حاصل کنید که ارزها را به درستی مدیریت می‌کنید. از کتابخانه‌ای مانند currency.js برای انجام محاسبات و تبدیل‌های دقیق ارز استفاده کنید.
• دسترسی‌پذیری برای کاربران متنوع: حتماً از دستورالعمل‌های دسترسی‌پذیری پیروی کنید تا اطمینان حاصل شود که فرم شما برای افراد دارای معلولیت قابل استفاده است. این شامل ارائه ویژگی‌های ARIA مناسب، استفاده از HTML معنایی و اطمینان از دسترسی‌پذیری فرم با صفحه‌کلید است. کاربران با اختلالات بینایی، شنوایی، تفاوت‌های شناختی و محدودیت‌های مهارت‌های حرکتی را در نظر بگیرید.
• تأخیر شبکه: از مشکلات احتمالی تأخیر شبکه، به ویژه برای کاربران در مناطقی با اتصال اینترنت کندتر، آگاه باشید. در طول فرآیند ارسال فرم، بازخورد واضحی مانند نشانگر بارگذاری یا نوار پیشرفت به کاربر ارائه دهید.
• شفافیت پیام خطا: اطمینان حاصل کنید که پیام‌های خطا صرف نظر از مکان یا مهارت فنی کاربر، واضح، مختصر و قابل اجرا هستند. از اصطلاحات فنی خودداری کنید.
• قوانین اعتبارسنجی: قوانین اعتبارسنجی مانند فرمت‌های کد پستی، فرمت‌های شماره تلفن و الزامات آدرس را برای مطابقت با قراردادهای مورد انتظار در مناطق مختلف بومی‌سازی کنید.

ادغام با کتابخانه‌های شخص ثالث

experimental_useFormStatus می‌تواند به طور یکپارچه با کتابخانه‌های مختلف فرم شخص ثالث برای افزایش قابلیت‌های مدیریت فرم ادغام شود. در اینجا چند مثال آورده شده است:

• Formik: فرامیک یک کتابخانه فرم محبوب است که مدیریت وضعیت فرم و اعتبارسنجی را ساده می‌کند. با ترکیب Formik و experimental_useFormStatus، می‌توانید به راحتی وضعیت ارسال فرم‌های خود را پیگیری کرده و بازخورد آنی به کاربر ارائه دهید.
• React Hook Form: این کتابخانه فرم پرکاربرد دیگری است که عملکرد و انعطاف‌پذیری عالی ارائه می‌دهد. ادغام React Hook Form با experimental_useFormStatus به شما امکان می‌دهد ارسال فرم‌ها را مدیریت کرده و به‌روزرسانی‌های وضعیت را به روشی تمیز و کارآمد نمایش دهید.
• Yup: یاپ یک سازنده اسکیم (schema) برای تجزیه و اعتبارسنجی مقادیر است. Yup می‌تواند برای تعریف اسکیم‌های اعتبارسنجی برای فرم‌های شما استفاده شود و experimental_useFormStatus می‌تواند برای نمایش خطاهای اعتبارسنجی به کاربر به صورت آنی استفاده شود.

برای ادغام با این کتابخانه‌ها، ممکن است پراپ action را به کامپوننت فرم یا تابع کنترل‌کننده کتابخانه منتقل کنید و سپس از experimental_useFormStatus در کامپوننت‌های مربوطه‌ای که نیاز به نمایش وضعیت ارسال دارند، استفاده کنید.

مقایسه با رویکردهای جایگزین

قبل از experimental_useFormStatus، توسعه‌دهندگان اغلب به مدیریت وضعیت دستی یا هوک‌های سفارشی برای پیگیری وضعیت ارسال فرم تکیه می‌کردند. این رویکردها می‌توانند دست‌وپاگیر و مستعد خطا باشند. experimental_useFormStatus روشی اعلانی‌تر و مختصرتر برای مدیریت ارسال فرم‌ها ارائه می‌دهد که کد تکراری را کاهش داده و خوانایی کد را بهبود می‌بخشد.

جایگزین‌های دیگر ممکن است شامل استفاده از کتابخانه‌هایی مانند `react-query` یا `swr` برای مدیریت تغییرات داده‌های سمت سرور باشد که می‌توانند به طور ضمنی ارسال فرم‌ها را مدیریت کنند. با این حال، experimental_useFormStatus روشی مستقیم‌تر و متمرکز بر React برای پیگیری وضعیت فرم ارائه می‌دهد، به ویژه هنگام استفاده از React Server Actions.

محدودیت‌ها و ملاحظات

در حالی که experimental_useFormStatus مزایای قابل توجهی ارائه می‌دهد، آگاهی از محدودیت‌ها و ملاحظات آن مهم است:

• وضعیت آزمایشی: همانطور که از نامش پیداست، experimental_useFormStatus هنوز در مرحله آزمایشی است. این بدان معناست که API آن ممکن است در آینده تغییر کند.
• وابستگی به سرور اکشن‌ها: این هوک به شدت با React Server Actions گره خورده است. نمی‌توان از آن با ارسال‌های فرم سنتی سمت کلاینت استفاده کرد.
• سازگاری مرورگر: اطمینان حاصل کنید که مرورگرهای هدف شما از ویژگی‌های لازم برای React Server Actions و experimental_useFormStatus پشتیبانی می‌کنند.

نتیجه‌گیری

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

به یاد داشته باشید که همیشه برای به‌روزترین اطلاعات در مورد experimental_useFormStatus و سایر ویژگی‌های آزمایشی، به مستندات رسمی React مراجعه کنید. کدنویسی خوشی داشته باشید!