generateStaticParams

يمكن استخدام دالة generateStaticParams بالاشتراك مع شرائح المسار الديناميكية لإنشاء مسارات بشكل ثابت أثناء وقت البناء بدلاً من الطلب عند وقت الطلب.

// إرجاع قائمة من `params` لملء الشريحة الديناميكية [slug]
export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  return posts.map((post) => ({
    slug: post.slug,
  }))
}

// سيتم إنشاء نسخ متعددة من هذه الصفحة بشكل ثابت
// باستخدام `params` التي تم إرجاعها بواسطة `generateStaticParams`
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  // ...
}

// إرجاع قائمة من `params` لملء الشريحة الديناميكية [slug]
export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  return posts.map((post) => ({
    slug: post.slug,
  }))
}

// سيتم إنشاء نسخ متعددة من هذه الصفحة بشكل ثابت
// باستخدام `params` التي تم إرجاعها بواسطة `generateStaticParams`
export default async function Page({ params }) {
  const { slug } = await params
  // ...
}

معلومة مفيدة:

يمكنك استخدام خيار تكوين شريحة dynamicParams للتحكم فيما يحدث عند زيارة شريحة ديناميكية لم يتم إنشاؤها باستخدام generateStaticParams.

يجب عليك إرجاع مصفوفة فارغة من generateStaticParams أو استخدام export const dynamic = 'force-static' لإعادة التحقق (ISR) للمسارات في وقت التشغيل.

أثناء next dev، سيتم استدعاء generateStaticParams عند الانتقال إلى مسار.

أثناء next build، يعمل generateStaticParams قبل إنشاء التنسيقات أو الصفحات المقابلة.

أثناء إعادة التحقق (ISR)، لن يتم استدعاء generateStaticParams مرة أخرى.

generateStaticParams يحل محل دالة getStaticPaths في موجه الصفحات.

المعاملات

options.params (اختياري)

إذا استخدمت عدة شرائح ديناميكية في مسار generateStaticParams، يتم تنفيذ دالة generateStaticParams الفرعية مرة واحدة لكل مجموعة من params التي ينشئها الأصل.

يحتوي كائن params على params المملوءة من generateStaticParams الأصلية، والتي يمكن استخدامها لإنشاء params في شريحة فرعية.

القيم المرجعة

يجب أن ترجع generateStaticParams مصفوفة من الكائنات حيث يمثل كل كائن الشرائح الديناميكية المملوءة لمسار واحد.

كل خاصية في الكائن هي شريحة ديناميكية يجب ملؤها للمسار.
اسم الخاصية هو اسم الشريحة، وقيمة الخاصية هي ما يجب ملء الشريحة به.

مثال المسار	نوع الإرجاع لـ `generateStaticParams`
`/product/[id]`	`{ id: string }[]`
`/products/[category]/[product]`	`{ category: string, product: string }[]`
`/products/[...slug]`	`{ slug: string[] }[]`

شريحة ديناميكية واحدة

export function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }, { id: '3' }]
}

// سيتم إنشاء ثلاث نسخ من هذه الصفحة بشكل ثابت
// باستخدام `params` التي تم إرجاعها بواسطة `generateStaticParams`
// - /product/1
// - /product/2
// - /product/3
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  // ...
}

export function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }, { id: '3' }]
}

// سيتم إنشاء ثلاث نسخ من هذه الصفحة بشكل ثابت
// باستخدام `params` التي تم إرجاعها بواسطة `generateStaticParams`
// - /product/1
// - /product/2
// - /product/3
export default async function Page({ params }) {
  const { id } = await params
  // ...
}

شرائح ديناميكية متعددة

export function generateStaticParams() {
  return [
    { category: 'a', product: '1' },
    { category: 'b', product: '2' },
    { category: 'c', product: '3' },
  ]
}

// سيتم إنشاء ثلاث نسخ من هذه الصفحة بشكل ثابت
// باستخدام `params` التي تم إرجاعها بواسطة `generateStaticParams`
// - /products/a/1
// - /products/b/2
// - /products/c/3
export default async function Page({
  params,
}: {
  params: Promise<{ category: string; product: string }>
}) {
  const { category, product } = await params
  // ...
}

export function generateStaticParams() {
  return [
    { category: 'a', product: '1' },
    { category: 'b', product: '2' },
    { category: 'c', product: '3' },
  ]
}

// سيتم إنشاء ثلاث نسخ من هذه الصفحة بشكل ثابت
// باستخدام `params` التي تم إرجاعها بواسطة `generateStaticParams`
// - /products/a/1
// - /products/b/2
// - /products/c/3
export default async function Page({ params }) {
  const { category, product } = await params
  // ...
}

شريحة ديناميكية شاملة

export function generateStaticParams() {
  return [{ slug: ['a', '1'] }, { slug: ['b', '2'] }, { slug: ['c', '3'] }]
}

// سيتم إنشاء ثلاث نسخ من هذه الصفحة بشكل ثابت
// باستخدام `params` التي تم إرجاعها بواسطة `generateStaticParams`
// - /product/a/1
// - /product/b/2
// - /product/c/3
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string[] }>
}) {
  const { slug } = await params
  // ...
}

export function generateStaticParams() {
  return [{ slug: ['a', '1'] }, { slug: ['b', '2'] }, { slug: ['c', '3'] }]
}

// سيتم إنشاء ثلاث نسخ من هذه الصفحة بشكل ثابت
// باستخدام `params` التي تم إرجاعها بواسطة `generateStaticParams`
// - /product/a/1
// - /product/b/2
// - /product/c/3
export default async function Page({ params }) {
  const { slug } = await params
  // ...
}

أمثلة

التصيير الثابت

جميع المسارات في وقت البناء

لتصيير جميع المسارات بشكل ثابت في وقت البناء، قم بتوفير القائمة الكاملة للمسارات إلى generateStaticParams:

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  return posts.map((post) => ({
    slug: post.slug,
  }))
}

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  return posts.map((post) => ({
    slug: post.slug,
  }))
}

مجموعة فرعية من المسارات في وقت البناء

لتصيير مجموعة فرعية من المسارات بشكل ثابت في وقت البناء، والباقي عند زيارتها لأول مرة في وقت التشغيل، قم بإرجاع قائمة جزئية من المسارات:

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  // تصيير أول 10 منشورات في وقت البناء
  return posts.slice(0, 10).map((post) => ({
    slug: post.slug,
  }))
}

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())

  // تصيير أول 10 منشورات في وقت البناء
  return posts.slice(0, 10).map((post) => ({
    slug: post.slug,
  }))
}

ثم، باستخدام خيار تكوين شريحة dynamicParams، يمكنك التحكم فيما يحدث عند زيارة شريحة ديناميكية لم يتم إنشاؤها باستخدام generateStaticParams.

// جميع المنشورات باستثناء العشرة الأوائل ستكون 404
export const dynamicParams = false

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())
  const topPosts = posts.slice(0, 10)

  return topPosts.map((post) => ({
    slug: post.slug,
  }))
}

// جميع المنشورات باستثناء العشرة الأوائل ستكون 404
export const dynamicParams = false

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())
  const topPosts = posts.slice(0, 10)

  return topPosts.map((post) => ({
    slug: post.slug,
  }))
}

جميع المسارات في وقت التشغيل

لتصيير جميع المسارات بشكل ثابت عند زيارتها لأول مرة، قم بإرجاع مصفوفة فارغة (لن يتم تصيير أي مسارات في وقت البناء) أو استخدم export const dynamic = 'force-static':

app/blog/[slug]/page.js

export async function generateStaticParams() {
  return []
}

معلومة مفيدة: يجب عليك دائمًا إرجاع مصفوفة من generateStaticParams، حتى لو كانت فارغة. وإلا، سيتم تصيير المسار بشكل ديناميكي.

app/changelog/[slug]/page.js

export const dynamic = 'force-static'

تعطيل التصيير للمسارات غير المحددة

لمنع تصيير المسارات غير المحددة بشكل ثابت في وقت التشغيل، أضف خيار export const dynamicParams = false في شريحة المسار. عند استخدام خيار التكوين هذا، سيتم تقديم المسارات المقدمة بواسطة generateStaticParams فقط، وستظهر المسارات غير المحددة كـ 404 أو تتطابق (في حالة مسارات الشاملة).

شرائح ديناميكية متعددة في مسار واحد

يمكنك إنشاء params للشرائح الديناميكية فوق التنسيق أو الصفحة الحالية، ولكن ليس تحتها. على سبيل المثال، بالنظر إلى مسار app/products/[category]/[product]:

يمكن لـ app/products/[category]/[product]/page.js إنشاء params لكل من [category] و [product].
يمكن لـ app/products/[category]/layout.js إنشاء params لـ [category] فقط.

هناك طريقتان لإنشاء params لمسار يحتوي على شرائح ديناميكية متعددة:

إنشاء params من الأسفل إلى الأعلى

إنشاء شرائح ديناميكية متعددة من شريحة المسار الفرعية.

// إنشاء شرائح لكل من [category] و [product]
export async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())

  return products.map((product) => ({
    category: product.category.slug,
    product: product.id,
  }))
}

export default function Page({
  params,
}: {
  params: Promise<{ category: string; product: string }>
}) {
  // ...
}

// إنشاء شرائح لكل من [category] و [product]
export async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())

  return products.map((product) => ({
    category: product.category.slug,
    product: product.id,
  }))
}

export default function Page({ params }) {
  // ...
}

إنشاء params من الأعلى إلى الأسفل

إنشاء الشرائح الأصلية أولاً واستخدام النتيجة لإنشاء الشرائح الفرعية.

// إنشاء شرائح لـ [category]
export async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())

  return products.map((product) => ({
    category: product.category.slug,
  }))
}

export default function Layout({
  params,
}: {
  params: Promise<{ category: string }>
}) {
  // ...
}

// إنشاء شرائح لـ [category]
export async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())

  return products.map((product) => ({
    category: product.category.slug,
  }))
}

export default function Layout({ params }) {
  // ...
}

يتم تنفيذ دالة generateStaticParams لشريحة المسار الفرعية مرة واحدة لكل شريحة ينشئها الأصل generateStaticParams.

يمكن لدالة generateStaticParams الفرعية استخدام params المرجعة من دالة generateStaticParams الأصلية لإنشاء شرائحها الخاصة بشكل ديناميكي.

// إنشاء شرائح لـ [product] باستخدام `params` الممررة من
// دالة `generateStaticParams` للشريحة الأصلية
export async function generateStaticParams({
  params: { category },
}: {
  params: { category: string }
}) {
  const products = await fetch(
    `https://.../products?category=${category}`
  ).then((res) => res.json())

  return products.map((product) => ({
    product: product.id,
  }))
}

export default function Page({
  params,
}: {
  params: Promise<{ category: string; product: string }>
}) {
  // ...
}

// إنشاء شرائح لـ [product] باستخدام `params` الممررة من
// دالة `generateStaticParams` للشريحة الأصلية
export async function generateStaticParams({ params: { category } }) {
  const products = await fetch(
    `https://.../products?category=${category}`
  ).then((res) => res.json())

  return products.map((product) => ({
    product: product.id,
  }))
}

export default function Page({ params }) {
  // ...
}

معلومة مفيدة: يتم تخزين طلبات fetch تلقائيًا لنفس البيانات عبر جميع الدوال ذات البادئة generate، والتنسيقات، والصفحات، ومكونات الخادم. يمكن استخدام cache من React إذا لم يكن fetch متاحًا.

تاريخ الإصدارات

الإصدار	التغييرات
`v13.0.0`	تم تقديم `generateStaticParams`.

On this page