فراخوانی توابع سرور

پس از تعریف توابع سرور، به دو روش اصلی می‌توانید آن‌ها را در لایه فرانت‌اند اپلیکیشن خود فراخوانی (Invoke) کنید: ۱. از طریق فرم‌ها (Forms): هم در کامپوننت‌های سرور و هم در کامپوننت‌های کلاینت. ۲. از طریق رویدادها (Event Handlers) و useEffect: فقط در کامپوننت‌های کلاینت.

چیزهایی که در این درس یاد می‌گیرید:

• نحوه اتصال مستقیم Server Functionها به ویژگی action در فرم‌ها

• روش استخراج داده‌ها با استفاده از شیء استاندارد FormData

• فراخوانی توابع سرور در رویدادهایی مثل onClick و مدیریت ناهمگام استیت کلاینت

📌 یک نکته مهم برای بهینه‌سازی: توابع سرور اساساً برای اعمال تغییرات و جهش داده‌ها در سمت سرور (Server-side mutations) طراحی شده‌اند. کلاینت در حال حاضر این توابع را به صورت تکی و پشت سر هم (One at a time) ارسال و منتظر پاسخ آن‌ها می‌ماند. اگر برای لود شدن صفحه نیاز به دریافت موازی داده‌ها (Parallel data fetching) دارید، نباید از Server Actions زنجیره‌ای استفاده کنید؛ بلکه باید دیتای خود را مستقیماً درون یک Server Component دریافت کنید، یا کارهای موازی را درون بدنه یک تابع سرور واحد یا یک Route Handler پیاده‌سازی کنید.

۱. فراخوانی از طریق فرم‌ها (Forms)

ری‌آکت المان استاندارد <form> در HTML را گسترش داده است تا بتواند یک تابع سرور را مستقیماً از طریق ویژگی action پذیرا باشد.

وقتی یک Server Function به ویژگی action فرم متصل می‌شود، در زمان سابمیت، به صورت خودکار شیء بومی FormData را به عنوان اولین آرگومان ورودی دریافت می‌کند. شما می‌توانید با متدهای استاندارد جاوااسکریپت (مثل .get()) اطلاعات فرم را از آن استخراج کنید:

لایه کلاینت یا سرور (فرم تعاملی)

// app/ui/form.tsx
import { createPost } from '@/app/actions'
 
export function Form() {
  return (
    // تابع createPost به محض فشرده شدن دکمه با دیتای فرم صدا زده می‌شود
    <form action={createPost}>
      <input type="text" name="title" />
      <input type="text" name="content" />
      <button type="submit">ایجاد پست</button>
    </form>
  )
}

لایه سرور (اکشن فرم)

// app/actions.ts
'use server'
 
import { auth } from '@/lib/auth'
 
export async function createPost(formData: FormData) {
  const session = await auth()
  // بررسی وضعیت احراز هویت کاربر روی سرور
  if (!session?.user) {
    throw new Error('Unauthorized')
  }
 
  // استخراج فیلدها با استفاده از ویژگی name در تگ‌های input
  const title = formData.get('title')
  const content = formData.get('content')
 
  // ۱. اعمال تغییرات در دیتابیس (Mutate data)
  // ۲. اعتبارسنجی مجدد کش برای به‌روزرسانی UI (Revalidate cache)
}

۲. فراخوانی از طریق مدیریت‌کننده‌های رویداد (Event Handlers)

شما محدود به فرم‌ها نیستید؛ در کامپوننت‌های کلاینت ('use client') می‌توانید توابع سرور را درون هر نوع رویدادی (مثل onClick ، onChange و...) یا حتی دستورات درون useEffect مانند یک تابع async معمولی فراخوانی کنید.

در این حالت، تابع سرور می‌تواند یک مقدار (Response) را پس از پردازش روی سرور به کلاینت برگرداند تا شما استیت کامپوننت کلاینت خود را با آن آپدیت کنید.

به این نمونه دکمه لایک نگاه کنید:

// app/like-button.tsx
'use client'
 
import { incrementLike } from './actions'
import { useState } from 'react'
 
export default function LikeButton({ initialLikes }: { initialLikes: number }) {
  const [likes, setLikes] = useState(initialLikes)
 
  return (
    <>
      <p>تعداد لایک‌ها: {likes}</p>
      <button
        onClick={async () => {
          // فراخوانی ناهمگام تابع روی سرور و دریافت خروجی جدید
          const updatedLikes = await incrementLike()
          
          // به‌روزرسانی استیت کلاینت با مقدار بازگشتی از سرور
          setLikes(updatedLikes)
        }}
      >
        لایک کردن
      </button>
    </>
  )
}

در این سناریو، به محض کلیک کاربر روی دکمه: ۱. مرورگر یک درخواست امن به سرور می‌فرستد تا تابع incrementLike را اجرا کند.

۲. سرور مقدار لایک را در دیتابیس افزایش داده و عدد جدید را ریترن می‌کند.

۳. بلاک onClick در کلاینت منتظر پاسخ (await) می‌ماند و با دریافت عدد جدید، استیت محلی کامپوننت را با setLikes آپدیت می‌کند تا صفحه بدون رفرش شدن تغییر کند.

خلاصه نکات کلیدی (Recap)

• توابع سرور را می‌توان هم به ویژگی action در فرم‌ها متصل کرد و هم درون Event Handlerها (مثل onClick) فراخوانی کرد.

• فرم‌هایی که از توابع سرور استفاده می‌کنند، نمونه شیء بومی FormData را به عنوان ورودی به تابع تحویل می‌دهند.

• توابع سرور در پس‌زمینه به صورت پیاپی و تک‌به‌تک اجرا می‌شوند و گزینه مناسبی برای دریافت موازی داده‌ها در زمان لود صفحه نیستند.

• در زمان فراخوانی توابع سرور از طریق رویدادها، می‌توانید دیتای بازگشتی از سرور را مستقیماً برای ویرایش استیت‌های کلاینت (useState) به کار بگیرید.