next/root-params
提供对根级路由参数访问的 next/root-params 模块的 API 参考。
next/root-params 模块提供 getter 函数,用于访问 Server Components 中的根级参数。每个根参数都作为异步函数导出,该函数解析为当前路由的参数值。
导出名称根据你的动态片段文件夹名称生成。例如,如果你的根布局位于 app/[locale] 内,则从 next/root-params 导入 locale。
这对于需要跨应用程序访问的值(例如语言或区域设置片段)很有用,例如在共享工具函数、布局和深层嵌套的组件中访问,而无需将它们作为 props 逐层传递。
import { lang } from 'next/root-params'
export default async function RootLayout(props: LayoutProps<'/[lang]'>) {
return (
<html lang={await lang()}>
<body>{props.children}</body>
</html>
)
}import { lang } from 'next/root-params'
export default async function RootLayout({ children }) {
return (
<html lang={await lang()}>
<body>{children}</body>
</html>
)
}根参数是出现在根布局之前的动态片段。与常规的 params prop不同,根参数 getter 可以从应用程序中的任何 Server Component 调用,而无需逐层传递 props。有关更多细节,请参阅为什么根参数特殊。
小知识:
- 根参数名称必须是有效的 JavaScript 函数标识符。不支持短横线命名的片段名称(例如
[post-slug]),否则会在开发时或构建期间导致错误。next/root-params可用于 Server Components。它不能用于 Client Components、Server Actions 或 Route Handlers。对 Route Handlers 的支持计划在未来版本中实现。next/root-params导出的类型会在next dev、next build或next typegen期间生成,与PageProps和LayoutProps相同。
根参数与 generateStaticParams#
一旦创建了定义根参数的路由,根参数就可用了。只有在使用 Cache Components 时才需要 generateStaticParams 函数,此时每个根参数必须至少有一个值,否则构建会失败。
使用单个根参数时:
import { lang } from 'next/root-params'
export default async function RootLayout(props: LayoutProps<'/[lang]'>) {
return (
<html lang={await lang()}>
<body>{props.children}</body>
</html>
)
}
export async function generateStaticParams() {
return [{ lang: 'en' }, { lang: 'fr' }]
}import { lang } from 'next/root-params'
export default async function RootLayout({ children }) {
return (
<html lang={await lang()}>
<body>{children}</body>
</html>
)
}
export async function generateStaticParams() {
return [{ lang: 'en' }, { lang: 'fr' }]
}使用多个根参数时,为每个参数返回一个值:
export async function generateStaticParams() {
return [
{ lang: 'en', locale: 'us' },
{ lang: 'en', locale: 'uk' },
]
}在嵌套的 generateStaticParams 中读取根参数#
在嵌套片段的 generateStaticParams 中,你可以直接用其 getter 读取根参数,而不是从 params 参数中解构它:
import { lang } from 'next/root-params'
export async function generateStaticParams() {
const language = await lang()
const posts = await fetch(
`https://api.example.com/posts?lang=${language}`
).then((res) => res.json())
return posts.map((post) => ({ slug: post.slug }))
}
export default async function Page() {
// ...
}import { lang } from 'next/root-params'
export async function generateStaticParams() {
const language = await lang()
const posts = await fetch(
`https://api.example.com/posts?lang=${language}`
).then((res) => res.json())
return posts.map((post) => ({ slug: post.slug }))
}
export default async function Page() {
// ...
}根参数与其他路由参数#
根参数是路径中出现在根布局文件之前的动态片段所对应的路由参数。路由树中更深层的其他路由参数则通过 params prop 访问。
给定以下文件结构:
app/[lang]/layout.tsx(根布局)app/[lang]/posts/[slug]/page.tsx
只有 lang 是根参数。slug 是常规路由参数:
import { lang } from 'next/root-params'
export default async function PostPage(
props: PageProps<'/[lang]/posts/[slug]'>
) {
const { slug } = await props.params
const language = await lang()
return (
<article>
<p>Language: {language}</p>
<p>Post: {slug}</p>
</article>
)
}import { lang } from 'next/root-params'
export default async function PostPage({ params }) {
const { slug } = await params
const language = await lang()
return (
<article>
<p>Language: {language}</p>
<p>Post: {slug}</p>
</article>
)
}在共享代码中访问根参数#
根参数 getter 是模块导入,可以从任何 Server Component 或服务端工具函数中调用,而不仅限于布局和页面:
import { lang } from 'next/root-params'
export async function getTranslations() {
const language = await lang()
// 根据根语言参数加载翻译
return import(`@/locales/${language}.json`)
}小知识: 对于使用
next/root-params的文件,你无需添加import 'server-only'。如果在 Client Component 中使用该导入,它会在构建时直接失败。
使用缓存指令时的行为#
由于根参数 getter 是导入的函数,Next.js 可以跟踪 缓存函数使用了哪些根参数。只有这些根参数会成为缓存键的一部分,因此缓存条目不会因无关的参数值而被拆分。
import { lang } from 'next/root-params'
// 此函数的缓存键仅包含 `lang`,
// 而不是路由中的每个动态片段。
async function getNavigation() {
'use cache'
const language = await lang()
const res = await fetch(`https://api.example.com/nav?lang=${language}`)
return res.json()
}
export default async function CachedNav() {
const nav = await getNavigation()
return <nav></nav>
}import { lang } from 'next/root-params'
// 此函数的缓存键仅包含 `lang`,
// 而不是路由中的每个动态片段。
async function getNavigation() {
'use cache'
const language = await lang()
const res = await fetch(`https://api.example.com/nav?lang=${language}`)
return res.json()
}
export default async function CachedNav() {
const nav = await getNavigation()
return <nav></nav>
}使用常规的 params prop 时,你需要在缓存函数外部 await params,并将该值作为参数传入:
import { lang } from 'next/root-params'
// 使用根参数:在缓存函数内部直接调用
async function getDataWithRootParams() {
'use cache'
const language = await lang()
return fetch(`https://api.example.com/data?lang=${language}`)
}
// 不使用根参数:在外部 await params,然后作为参数传入
async function getDataWithParams(language: string) {
'use cache'
return fetch(`https://api.example.com/data?lang=${language}`)
}
export default async function Page(props: PageProps<'/[lang]'>) {
const { lang: language } = await props.params
const data = await getDataWithParams(language)
// ...
}import { lang } from 'next/root-params'
// 使用根参数:在缓存函数内部直接调用
async function getDataWithRootParams() {
'use cache'
const language = await lang()
return fetch(`https://api.example.com/data?lang=${language}`)
}
// 不使用根参数:在外部 await params,然后作为参数传入
async function getDataWithParams(language) {
'use cache'
return fetch(`https://api.example.com/data?lang=${language}`)
}
export default async function Page({ params }) {
const { lang: language } = await params
const data = await getDataWithParams(language)
// ...
}多个根布局#
当应用程序具有多个使用不同参数的根布局时,getter 函数的类型会考虑在所有可能路由中的使用情况。并非存在于每个根布局中的参数的类型为 string | undefined。
给定以下文件结构:
app/dashboard/[id]/layout.tsx(带id的根布局)app/marketing/layout.tsx(不带id的根布局)
import { id } from 'next/root-params'
export default async function DashboardPage() {
const dashboardId = await id() // string | undefined
return <div>Dashboard: {dashboardId}</div>
}import { id } from 'next/root-params'
export default async function DashboardPage() {
const dashboardId = await id() // string | undefined
return <div>Dashboard: {dashboardId}</div>
}由于 id 在 marketing 根布局中不存在,从 marketing 路由访问时 await id() 会返回 undefined。
全部捕获和可选全部捕获片段#
根参数可与全部捕获和可选全部捕获片段一起使用:
import { path } from 'next/root-params'
export default async function DocsLayout(
props: LayoutProps<'/docs/[...path]'>
) {
const segments = await path() // string[] | undefined
return (
<div>
<nav>Path: {segments?.join(' / ')}</nav>
{props.children}
</div>
)
}import { path } from 'next/root-params'
export default async function DocsLayout({ children }) {
const segments = await path() // string[] | undefined
return (
<div>
<nav>Path: {segments?.join(' / ')}</nav>
{children}
</div>
)
}返回值#
每个根参数 getter 都返回一个 Promise,其解析结果为以下之一:
| 片段类型 | 示例 | 返回类型 |
|---|---|---|
| 动态 | [id] | string |
| 全部捕获 | [...path] | string[] |
| 可选全部捕获 | [[...path]] | `string[] \ |
如果该参数在当前路由的根布局中不存在(请参阅多个根布局),则返回类型会包含 undefined。
限制#
其中大多数是根参数工作方式的永久性约束。例外是 Route Handlers,它目前尚不受支持,但计划在未来版本中实现。
仅限 Server Components#
根参数 getter 只能在 Server Components 中使用:
// 这将导致构建错误
'use client'
import { lang } from 'next/root-params' // 错误:无法在 Client Component 中导入在 unstable_cache 中不可用#
在 unstable_cache 中调用根参数 getter 会抛出运行时错误。请改用 "use cache"。
import { lang } from 'next/root-params'
import { unstable_cache } from 'next/cache'
const getCachedData = unstable_cache(async () => {
const language = await lang() // 错误:不支持在 unstable_cache 中使用
return fetch(`https://api.example.com/data?lang=${language}`)
})在 Server Actions 中不可用#
import { lang } from 'next/root-params'
async function submitForm() {
'use server'
const language = await lang() // 错误:不支持在 Server Actions 中使用
}为什么根参数特殊#
根布局是顶层渲染边界。它之前的路由参数由该根布局下的所有路由共享,这使得从该树中的任何 Server Component 访问它们都是安全的。路由中更深层的路由参数会随所渲染的子页面而变化,因此它们只能通过定义它们的页面或布局中的 params prop 获取。
app/
[lang]/ ← 根参数(由下方所有路由共享)
layout.tsx ← 根布局
page.tsx ← 没有 slug,不知道 blog 或 store
blog/
[slug]/ ← 路由参数
page.tsx
store/
[...slug]/ ← 同名的全部捕获路由参数
page.tsx在此示例中,lang 是唯一的根参数。直接位于根布局下的 page.tsx 完全没有 slug。blog 和 store 分支都定义了 slug,但使用了不同的片段类型([slug] 与 [...slug])。每条路由只知道自己的路由参数。同一个名称可能具有不同的类型、不同的含义,或在不同路由中根本不存在。这就是为什么根布局以下的路由参数通过 params prop 访问,而不是作为全局 getter 访问。
例外是多个根布局。当不同的根布局定义不同的路由参数时,getter 函数的返回类型会包含 undefined,以涵盖某个给定参数可能不存在的路由情况。
版本历史#
| 版本 | 更改 |
|---|---|
v16.3.0 | 引入 next/root-params。 |