getStaticProps

إذا قمت بتصدير دالة تسمى getStaticProps (إنشاء موقع ثابت) من صفحة، فإن Next.js سيقوم بعرض هذه الصفحة مسبقًا أثناء البناء باستخدام الخصائص التي تُرجعها getStaticProps.

import type { InferGetStaticPropsType, GetStaticProps } from 'next'

type Repo = {
  name: string
  stargazers_count: number
}

export const getStaticProps = (async (context) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}) satisfies GetStaticProps<{
  repo: Repo
}>

export default function Page({
  repo,
}: InferGetStaticPropsType<typeof getStaticProps>) {
  return repo.stargazers_count
}

export async function getStaticProps() {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}

export default function Page({ repo }) {
  return repo.stargazers_count
}

لاحظ أنه بغض النظر عن نوع العرض، سيتم تمرير أي props إلى مكون الصفحة ويمكن رؤيتها على جانب العميل في HTML الأولي. هذا للسماح للصفحة بأن تتم إعادة التميؤ (hydration) بشكل صحيح. تأكد من عدم تمرير أي معلومات حساسة لا يجب أن تكون متاحة على العميل في props.

مرجع واجهة برمجة التطبيقات getStaticProps يغطي جميع المعاملات والخصائص التي يمكن استخدامها مع getStaticProps.

متى يجب استخدام getStaticProps؟

يجب استخدام getStaticProps إذا:

• البيانات المطلوبة لعرض الصفحة متوفرة في وقت البناء قبل طلب المستخدم
• تأتي البيانات من نظام إدارة المحتوى (CMS) بدون واجهة أمامية
• يجب أن تكون الصفحة معروضة مسبقًا (لتحسين محركات البحث) وسريعة جدًا - getStaticProps يولد ملفات HTML و JSON، وكلاهما يمكن تخزينه مؤقتًا بواسطة CDN لتحسين الأداء
• يمكن تخزين البيانات بشكل علني (غير خاص بالمستخدم). يمكن تجاوز هذا الشرط في حالات محددة باستخدام Middleware لإعادة كتابة المسار.

متى يتم تشغيل getStaticProps

getStaticProps يعمل دائمًا على الخادم ولا يعمل أبدًا على العميل. يمكنك التحقق من إزالة الكود المكتوب داخل getStaticProps من حزمة جانب العميل باستخدام هذه الأداة.

• getStaticProps يعمل دائمًا أثناء next build
• getStaticProps يعمل في الخلفية عند استخدام fallback: true
• getStaticProps يتم استدعاؤه قبل العرض الأولي عند استخدام fallback: blocking
• getStaticProps يعمل في الخلفية عند استخدام revalidate
• getStaticProps يعمل عند الطلب في الخلفية عند استخدام revalidate()

عند استخدامه مع التجديد الثابت التدريجي (Incremental Static Regeneration)، سيعمل getStaticProps في الخلفية أثناء إعادة التحقق من الصفحة القديمة، وسيتم تقديم الصفحة الجديدة للمتصفح.

لا يمكن لـ getStaticProps الوصول إلى الطلب الوارد (مثل معلمات الاستعلام أو رؤوس HTTP) لأنه يولد HTML ثابتًا. إذا كنت بحاجة إلى الوصول إلى الطلب لصفحتك، ففكر في استخدام الوسيط (Middleware) بالإضافة إلى getStaticProps.

استخدام getStaticProps لجلب البيانات من نظام إدارة المحتوى (CMS)

يوضح المثال التالي كيفية جلب قائمة من منشورات المدونة من نظام إدارة المحتوى.

// سيتم ملء المنشورات في وقت البناء بواسطة getStaticProps()
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

// يتم استدعاء هذه الدالة في وقت البناء على جانب الخادم.
// لن يتم استدعاؤها على جانب العميل، لذا يمكنك حتى إجراء
// استعلامات قاعدة بيانات مباشرة.
export async function getStaticProps() {
  // استدعاء نقطة نهاية API خارجية للحصول على المنشورات.
  // يمكنك استخدام أي مكتبة لجلب البيانات
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // عن طريق إرجاع { props: { posts } }، سيستقبل مكون Blog
  // `posts` كخاصية في وقت البناء
  return {
    props: {
      posts,
    },
  }
}

// سيتم ملء المنشورات في وقت البناء بواسطة getStaticProps()
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

// يتم استدعاء هذه الدالة في وقت البناء على جانب الخادم.
// لن يتم استدعاؤها على جانب العميل، لذا يمكنك حتى إجراء
// استعلامات قاعدة بيانات مباشرة.
export async function getStaticProps() {
  // استدعاء نقطة نهاية API خارجية للحصول على المنشورات.
  // يمكنك استخدام أي مكتبة لجلب البيانات
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // عن طريق إرجاع { props: { posts } }، سيستقبل مكون Blog
  // `posts` كخاصية في وقت البناء
  return {
    props: {
      posts,
    },
  }
}

مرجع واجهة برمجة التطبيقات getStaticProps يغطي جميع المعاملات والخصائص التي يمكن استخدامها مع getStaticProps.

كتابة كود جانب الخادم مباشرة

بما أن getStaticProps يعمل فقط على جانب الخادم، فلن يعمل أبدًا على جانب العميل. لن يتم تضمينه حتى في حزمة JS للمتصفح، لذا يمكنك كتابة استعلامات قاعدة بيانات مباشرة دون إرسالها إلى المتصفحات.

هذا يعني أنه بدلاً من جلب مسار API من getStaticProps (الذي يجلب البيانات من مصدر خارجي)، يمكنك كتابة كود جانب الخادم مباشرة في getStaticProps.

خذ المثال التالي. يتم استخدام مسار API لجلب بعض البيانات من نظام إدارة المحتوى. ثم يتم استدعاء مسار API هذا مباشرة من getStaticProps. هذا ينتج عنه استدعاء إضافي، مما يقلل الأداء. بدلاً من ذلك، يمكن مشاركة منطق جلب البيانات من نظام إدارة المحتوى باستخدام دليل lib/. ثم يمكن مشاركته مع getStaticProps.

// الدالة التالية مشتركة
// مع getStaticProps ومسارات API
// من دليل `lib/`
export async function loadPosts() {
  // استدعاء نقطة نهاية API خارجية للحصول على المنشورات
  const res = await fetch('https://.../posts/')
  const data = await res.json()

  return data
}

// pages/blog.js
import { loadPosts } from '../lib/load-posts'

// هذه الدالة تعمل فقط على جانب الخادم
export async function getStaticProps() {
  // بدلاً من جلب مسار `/api` الخاص بك، يمكنك استدعاء نفس
  // الدالة مباشرة في `getStaticProps`
  const posts = await loadPosts()

  // الخصائص التي يتم إرجاعها سيتم تمريرها إلى مكون الصفحة
  return { props: { posts } }
}

بدلاً من ذلك، إذا كنت لا تستخدم مسارات API لجلب البيانات، فيمكن استخدام واجهة fetch() مباشرة في getStaticProps لجلب البيانات.

للتحقق مما يزيله Next.js من حزمة جانب العميل، يمكنك استخدام أداة next-code-elimination.

إنشاء كل من HTML و JSON بشكل ثابت

عند عرض صفحة تحتوي على getStaticProps مسبقًا في وقت البناء، بالإضافة إلى ملف HTML للصفحة، يقوم Next.js بإنشاء ملف JSON يحتوي على نتيجة تشغيل getStaticProps.

سيتم استخدام ملف JSON هذا في توجيه جانب العميل من خلال next/link أو next/router. عند الانتقال إلى صفحة تم عرضها مسبقًا باستخدام getStaticProps، يقوم Next.js بجلب ملف JSON هذا (المحسوب مسبقًا في وقت البناء) واستخدامه كخصائص لمكون الصفحة. هذا يعني أن انتقالات الصفحة على جانب العميل لن تستدعي getStaticProps حيث يتم استخدام ملف JSON المصدر فقط.

عند استخدام التجديد الثابت التدريجي، سيتم تنفيذ getStaticProps في الخلفية لإنشاء JSON المطلوب للتنقل على جانب العميل. قد ترى هذا في شكل طلبات متعددة لنفس الصفحة، ومع ذلك، هذا مقصود وليس له أي تأثير على أداء المستخدم النهائي.

أين يمكن استخدام getStaticProps

يمكن تصدير getStaticProps فقط من صفحة. لا يمكن تصديره من ملفات غير الصفحات، أو _app، أو _document، أو _error.

أحد أسباب هذا القيد هو أن React يحتاج إلى جميع البيانات المطلوبة قبل عرض الصفحة.

أيضًا، يجب عليك تصدير getStaticProps كدالة مستقلة - لن تعمل إذا أضفت getStaticProps كخاصية لمكون الصفحة.

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

يعمل على كل طلب في وضع التطوير

في وضع التطوير (next dev)، سيتم استدعاء getStaticProps على كل طلب.

وضع المعاينة

يمكنك تجاوز التوليد الثابت مؤقتًا وعرض الصفحة في وقت الطلب بدلاً من وقت البناء باستخدام وضع المعاينة (Preview Mode). على سبيل المثال، قد تستخدم نظام إدارة محتوى بدون واجهة أمامية وتريد معاينة المسودات قبل نشرها.