布局和模板

特殊文件 layout.js 和 template.js 允许你创建在路由之间共享的 UI。本页将指导你如何以及何时使用这些特殊文件。

布局

布局是在多个路由之间共享的 UI。在导航时，布局会保持状态，保持交互性，并且不会重新渲染。布局还可以嵌套。

你可以通过在 layout.js 文件中默认导出一个 React 组件来定义布局。该组件应接受一个 children 属性，在渲染期间将填充子布局（如果存在）或页面。

例如，布局将与 /dashboard 和 /dashboard/settings 页面共享：

app/dashboard/layout.tsx

TypeScript

export default function DashboardLayout({
  children, // 将是一个页面或嵌套布局
}: {
  children: React.ReactNode
}) {
  return (
    <section>
      {/* 在此处包含共享 UI，例如页眉或侧边栏 */}
      <nav></nav>
 
      {children}
    </section>
  )
}

根布局（必需）

根布局定义在 app 目录的顶层，适用于所有路由。这个布局是必需的，必须包含 html 和 body 标签，允许你修改从服务器返回的初始 HTML。

app/layout.tsx

TypeScript

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        {/* 布局 UI */}
        <main>{children}</main>
      </body>
    </html>
  )
}

嵌套布局

默认情况下，文件夹层次结构中的布局是嵌套的，这意味着它们通过 children 属性包装子布局。你可以通过在特定路由段（文件夹）中添加 layout.js 来嵌套布局。

例如，要为 /dashboard 路由创建布局，请在 dashboard 文件夹中添加新的 layout.js 文件：

app/dashboard/layout.tsx

TypeScript

export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return <section>{children}</section>
}

如果你要组合上面的两个布局，根布局（app/layout.js）将包装仪表板布局（app/dashboard/layout.js），后者将包装 app/dashboard/* 内的路由段。

这两个布局将嵌套如下：

值得注意的是：

布局可以使用 .js、.jsx 或 .tsx 文件扩展名。

只有根布局可以包含 <html> 和 <body> 标签。

当在同一文件夹中定义 layout.js 和 page.js 文件时，布局将包装页面。

布局默认是 Server Components，但可以设置为 Client Components。

布局可以获取数据。有关更多信息，请参阅数据获取部分。

无法在父布局和其子布局之间传递数据。但是，你可以在一个路由中多次获取相同的数据，React 会自动去重请求，而不会影响性能。

布局无法访问 pathname（了解更多）。但导入的 Client Components 可以使用 usePathname 钩子访问 pathname。

布局无法访问其下方的路由段。要访问所有路由段，你可以在 Client Component 中使用 useSelectedLayoutSegment 或 useSelectedLayoutSegments。

你可以使用路由组将特定路由段选择加入或退出共享布局。

你可以使用路由组创建多个根布局。点击此处查看示例。

从 pages 目录迁移： 根布局替代了 _app.js 和 _document.js 文件。查看迁移指南。

模板

模板与布局类似，它们都包装子布局或页面。但与在路由之间保持状态的布局不同，模板在导航时为其每个子项创建一个新实例。这意味着当用户在共享模板的路由之间导航时，子项的新实例将被挂载，DOM 元素将被重新创建，Client Components 中的状态不会被保留，并且效果将重新同步。

在某些情况下，你可能需要这些特定行为，模板可能比布局更适合。例如：

在导航时重新同步 useEffect。
在导航时重置子 Client Components 的状态。

通过从 template.js 文件中导出默认 React 组件可以定义模板。该组件应接受 children 属性。

app/template.tsx

TypeScript

export default function Template({ children }: { children: React.ReactNode }) {
  return <div>{children}</div>
}

在嵌套方面，template.js 在布局和其子项之间渲染。这里是简化的输出：

Output

<Layout>
  {/* 注意，模板被赋予一个唯一的键。 */}
  <Template key={routeParam}>{children}</Template>
</Layout>

示例

元数据

你可以使用 Metadata APIs 修改 <head> HTML 元素，如 title 和 meta。

可以通过在 layout.js 或 page.js 文件中导出 metadata 对象或 generateMetadata 函数来定义元数据。

app/page.tsx

TypeScript

import type { Metadata } from 'next'
 
export const metadata: Metadata = {
  title: 'Next.js',
}
 
export default function Page() {
  return '...'
}

值得注意的是：你不应手动向根布局添加 <head> 标签，如 <title> 和 <meta>。相反，应使用 Metadata API，它会自动处理高级需求，如流式传输和去重 <head> 元素。

在 API 参考中了解更多关于可用元数据选项的信息。

活动导航链接

你可以使用 usePathname() 钩子来确定导航链接是否处于活动状态。

由于 usePathname() 是一个客户端钩子，你需要将导航链接提取到 Client Component 中，然后可以将其导入到你的布局或模板中：

app/ui/nav-links.tsx

TypeScript

'use client'
 
import { usePathname } from 'next/navigation'
import Link from 'next/link'
 
export function NavLinks() {
  const pathname = usePathname()
 
  return (
    <nav>
      <Link className={`link ${pathname === '/' ? 'active' : ''}`} href="/">
        Home
      </Link>
 
      <Link
        className={`link ${pathname === '/about' ? 'active' : ''}`}
        href="/about"
      >
        About
      </Link>
    </nav>
  )
}

app/layout.tsx

TypeScript

import { NavLinks } from '@/app/ui/nav-links'
 
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <NavLinks />
        <main>{children}</main>
      </body>
    </html>
  )
}