layout.js
layout
文件用于在你的 Next.js 应用程序中定义布局。
export default function DashboardLayout({
children,
}: {
children: React.ReactNode
}) {
return <section>{children}</section>
}
根布局是根 app
目录中最顶层的布局。它用于定义 <html>
和 <body>
标签以及其他全局共享的 UI。
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
参考
Props
children
(必需)
布局组件应接受并使用 children
prop。在渲染期间,children
将填充布局正在包装的路由段。这些段主要将是子 布局(如果存在)或 页面的组件,但也可能是其他特殊文件,如 Loading 或 Error(如果适用)。
params
(可选)
一个 Promise,它解析为一个对象,其中包含从根段到该布局的 动态路由参数对象。
export default async function Layout({
params,
}: {
params: Promise<{ team: string }>
}) {
const team = (await params).team
}
路由示例 | URL | params |
---|---|---|
app/dashboard/[team]/layout.js | /dashboard/1 | Promise<{ team: '1' }> |
app/shop/[tag]/[item]/layout.js | /shop/1/2 | Promise<{ tag: '1', item: '2' }> |
app/blog/[...slug]/layout.js | /blog/1/2 | Promise<{ slug: ['1', '2'] }> |
- 由于
params
prop 是一个 promise。你必须使用async/await
或 React 的use
函数来访问这些值。- 在版本 14 及更早版本中,
params
是一个同步 prop。为了帮助向后兼容,你仍然可以在 Next.js 15 中同步访问它,但此行为将在未来被弃用。
- 在版本 14 及更早版本中,
根布局
app
目录必须包含一个根 app/layout.js
。
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html>
<body>{children}</body>
</html>
)
}
- 根布局必须定义
<html>
和<body>
标签。- 你不应该手动向根布局添加
<head>
标签,例如<title>
和<meta>
。相反,你应该使用 Metadata API,它会自动处理高级需求,例如流式处理和去重<head>
元素。
- 你不应该手动向根布局添加
- 你可以使用 路由组来创建多个根布局。
- 跨多个根布局导航将导致完整的页面加载(而不是客户端导航)。例如,从使用
app/(shop)/layout.js
的/cart
导航到使用app/(marketing)/layout.js
的/blog
将导致完整的页面加载。这仅适用于多个根布局。
- 跨多个根布局导航将导致完整的页面加载(而不是客户端导航)。例如,从使用
注意事项
布局不接收 searchParams
与 页面 不同,布局组件不接收 searchParams
prop。这是因为共享布局在 导航期间不会重新渲染,这可能导致导航之间出现过时的 searchParams
。
当使用客户端导航时,Next.js 会自动仅渲染两个路由之间公共布局下方的页面部分。
例如,在以下目录结构中,dashboard/layout.tsx
是 /dashboard/settings
和 /dashboard/analytics
的公共布局


当从 /dashboard/settings
导航到 /dashboard/analytics
时,/dashboard/analytics
中的 page.tsx
将在服务器上重新渲染,而 dashboard/layout.tsx
将不会重新渲染,因为它是在两个路由之间共享的公共 UI。
这种性能优化允许在共享布局的页面之间进行更快的导航,因为只需运行页面的数据获取和渲染,而不是可能包含获取自身数据的共享布局的整个路由。
由于 dashboard/layout.tsx
不会重新渲染,因此布局服务器组件中的 searchParams
prop 在导航后可能会变得过时。
相反,请在布局中使用页面 searchParams
prop 或客户端组件中的 useSearchParams
hook,它将在客户端使用最新的 searchParams
重新渲染。
布局无法访问 pathname
布局无法访问 pathname
。这是因为布局默认是服务器组件,并且 在客户端导航期间不重新渲染,这可能导致 pathname
在导航之间变得过时。为了防止过时,Next.js 需要重新获取路由的所有段,从而失去缓存的好处并增加导航时的 RSC payload 大小。
相反,你可以将依赖于 pathname 的逻辑提取到客户端组件中,并将其导入到你的布局中。由于客户端组件在导航期间重新渲染(但不会重新获取),你可以使用 Next.js hooks,例如 usePathname
来访问当前的 pathname 并防止过时。
import { ClientComponent } from '@/app/ui/ClientComponent'
export default function Layout({ children }: { children: React.ReactNode }) {
return (
<>
<ClientComponent />
{/* Other Layout UI */}
<main>{children}</main>
</>
)
}
常见的 pathname
模式也可以使用 params
prop 来实现。
有关更多信息,请参阅示例部分。
示例
基于 params
显示内容
使用 动态路由段,你可以基于 params
prop 显示或获取特定内容。
export default async function DashboardLayout({
children,
params,
}: {
children: React.ReactNode
params: Promise<{ team: string }>
}) {
const { team } = await params
return (
<section>
<header>
<h1>Welcome to {team}'s Dashboard</h1>
</header>
<main>{children}</main>
</section>
)
}
在客户端组件中读取 params
要在客户端组件(不能是 async
)中使用 params
,你可以使用 React 的 use
函数来读取 promise
'use client'
import { use } from 'react'
export default function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = use(params)
}
版本历史
版本 | 变更 |
---|---|
v15.0.0-RC | params 现在是一个 promise。 codemod 可用。 |
v13.0.0 | 引入 layout 。 |
这是否有帮助?