getStaticPaths

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

عندما تصدر دالة تسمى getStaticPaths (إنشاء موقع ثابت) من صفحة تستخدم مسارات ديناميكية، فإن Next.js سيقوم بعرض مسبقًا جميع المسارات المحددة بواسطة getStaticPaths بشكل ثابت.

import type {
  InferGetStaticPropsType,
  GetStaticProps,
  GetStaticPaths,
} from 'next'

type Repo = {
  name: string
  stargazers_count: number
}

export const getStaticPaths = (async () => {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // انظر قسم "paths" أدناه
    ],
    fallback: true, // false أو "blocking"
  }
}) satisfies GetStaticPaths

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 getStaticPaths() {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // انظر قسم "paths" أدناه
    ],
    fallback: true, // false أو "blocking"
  }
}

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
}

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

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

يجب استخدام getStaticPaths إذا كنت تقوم بعرض صفحات مسبقًا بشكل ثابت تستخدم مسارات ديناميكية و:

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

متى يتم تشغيل getStaticPaths

سيتم تشغيل getStaticPaths فقط أثناء البناء في بيئة الإنتاج، ولن يتم استدعاؤه أثناء وقت التشغيل. يمكنك التحقق من إزالة الكود المكتوب داخل getStaticPaths من حزمة جانب العميل باستخدام هذه الأداة.

كيف يعمل getStaticProps فيما يتعلق بـ getStaticPaths

يتم تشغيل getStaticProps أثناء next build لأي paths تم إرجاعها أثناء البناء
يتم تشغيل getStaticProps في الخلفية عند استخدام fallback: true
يتم استدعاء getStaticProps قبل العرض الأولي عند استخدام fallback: blocking

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

يجب استخدام getStaticPaths مع getStaticProps
لا يمكن استخدام getStaticPaths مع getServerSideProps
يمكنك تصدير getStaticPaths من مسار ديناميكي يستخدم أيضًا getStaticProps
لا يمكن تصدير getStaticPaths من ملف غير صفحة (مثل مجلد components)
يجب تصدير getStaticPaths كدالة مستقلة، وليس كخاصية لمكون الصفحة

التشغيل في كل طلب في بيئة التطوير

في بيئة التطوير (next dev)، سيتم استدعاء getStaticPaths في كل طلب.

إنشاء المسارات عند الطلب

يسمح getStaticPaths لك بالتحكم في الصفحات التي يتم إنشاؤها أثناء البناء بدلاً من إنشائها عند الطلب باستخدام fallback. إنشاء المزيد من الصفحات أثناء البناء سيؤدي إلى عمليات بناء أبطأ.

يمكنك تأجيل إنشاء جميع الصفحات عند الطلب عن طريق إرجاع مصفوفة فارغة لـ paths. يمكن أن يكون هذا مفيدًا بشكل خاص عند نشر تطبيق Next.js الخاص بك في بيئات متعددة. على سبيل المثال، يمكنك الحصول على عمليات بناء أسرع عن طريق إنشاء جميع الصفحات عند الطلب للمعاينات (وليس لبناء الإنتاج). هذا مفيد للمواقع التي تحتوي على مئات/آلاف الصفحات الثابتة.

pages/posts/[id].js

export async function getStaticPaths() {
  // عندما يكون هذا صحيحًا (في بيئات المعاينة) لا تقم
  // بعرض أي صفحات ثابتة مسبقًا
  // (عمليات بناء أسرع، ولكن تحميل الصفحة الأولي أبطأ)
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return {
      paths: [],
      fallback: 'blocking',
    }
  }

  // استدعاء نقطة نهاية API خارجية للحصول على المنشورات
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // الحصول على المسارات التي نريد عرضها مسبقًا بناءً على المنشورات
  // في بيئات الإنتاج، قم بعرض جميع الصفحات مسبقًا
  // (عمليات بناء أبطأ، ولكن تحميل الصفحة الأولي أسرع)
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // { fallback: false } يعني أن المسارات الأخرى يجب أن تعرض خطأ 404
  return { paths, fallback: false }
}