动态路由段

当您事先不知道确切的路由段名称，并希望从动态数据创建路由时，可以使用动态路由段，这些路由段可以在请求时填充或在构建时预渲染。

约定

动态路由段可以通过将文件夹名称用方括号包裹来创建：[folderName]。例如，一个博客可以包含以下路由 app/blog/[slug]/page.js，其中 [slug] 是博客文章的动态路由段。

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  return <div>My Post: {slug}</div>
}

动态路由段作为 params 属性传递给 layout、page、route 和 generateMetadata 函数。

在客户端组件中

在客户端组件的 page 中，可以使用 use 钩子访问来自 props 的动态路由段。

'use client'
import { use } from 'react'
 
export default function BlogPostPage({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = use(params)
 
  return (
    <div>
      <p>{slug}</p>
    </div>
  )
}

或者，客户端组件可以使用 useParams 钩子在客户端组件树中的任何位置访问 params。

捕获所有路由段

动态路由段可以通过在方括号内添加省略号 [...folderName] 来扩展，以 捕获所有 后续路由段。

例如，app/shop/[...slug]/page.js 将匹配 /shop/clothes，以及 /shop/clothes/tops、/shop/clothes/tops/t-shirts 等。

可选的捕获所有路由段

捕获所有路由段可以通过在双层方括号 [[...folderName]] 中包含参数来使其 可选。

例如，app/shop/[[...slug]]/page.js 除了匹配 /shop/clothes、/shop/clothes/tops、/shop/clothes/tops/t-shirts 之外，也 将匹配 /shop。

捕获所有 和 可选捕获所有 路由段之间的区别在于，可选的路由段也匹配不带参数的路由（在上述示例中为 /shop）。

TypeScript

使用 TypeScript 时，您可以根据您配置的路由段添加 params 的类型 — 分别使用 PageProps<'/route'>、LayoutProps<'/route'> 或 RouteContext<'/route'> 来为 page、layout 和 route 中的 params 定义类型。

路由 params 的值被类型化为 string、string[] 或 undefined（对于可选的捕获所有路由段），因为它们的值在运行时之前是未知的。用户可以在地址栏中输入任何 URL，这些宽泛的类型有助于确保您的应用程序代码处理所有这些可能的情况。

如果您正在处理一个 params 只能有固定数量有效值的路由，例如具有已知语言代码集的 [locale] 参数，您可以使用运行时验证来处理用户可能输入的任何无效参数，并让您的应用程序的其余部分使用您已知集中的更窄的类型。

import { notFound } from 'next/navigation'
import type { Locale } from '@i18n/types'
import { isValidLocale } from '@i18n/utils'
 
function assertValidLocale(value: string): asserts value is Locale {
  if (!isValidLocale(value)) notFound()
}
 
export default async function Page(props: PageProps<'/[locale]'>) {
  const { locale } = await props.params // locale is typed as string
  assertValidLocale(locale)
  // locale is now typed as Locale
}

行为

• 由于 params 属性是一个 Promise。您必须使用 async/await 或 React 的 use 函数来访问这些值。
  • 在 14 版及更早版本中，params 是一个同步属性。为了帮助实现向后兼容性，您仍然可以在 Next.js 15 中同步访问它，但此行为将来会被弃用。

示例

使用 generateStaticParams

generateStaticParams 函数可用于在构建时（而不是按需请求时）静态生成 路由。

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())
 
  return posts.map((post) => ({
    slug: post.slug,
  }))
}

在 generateStaticParams 函数内部使用 fetch 时，请求会 自动去重。这可以避免布局、页面和其他 generateStaticParams 函数对相同数据进行多次网络调用，从而加快构建时间。