NNext.js 中文网 GitHub

layout.js

layout.js 文件的 API 参考。

layout 文件用于在 Next.js 应用程序中定义布局。

app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return <section>{children}</section>
}
app/dashboard/layout.js
export default function DashboardLayout({ children }) {
  return <section>{children}</section>
}

在组件层次结构中,layout.js 是路由段中最外层的组件。它包裹 template.js、error.js、loading.js、not-found.js 和 page.js。

根布局(root layout)是根 app 目录中最顶层的布局。它用于定义 <html> 和 <body> 标签以及其他全局共享的 UI。

app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}
app/layout.js
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

参考#

Props#

children(必需)#

布局组件应接受并使用 children prop。在渲染期间,children 会被该布局所包裹的路由段填充。这些主要是子级布局(如果存在)或页面的组件,但在适用情况下也可能是其他特殊文件,例如 Loading 或 Error。

params(可选)#

一个 Promise,解析后得到一个对象,其中包含从根段到该布局的动态路由参数对象。

app/dashboard/[team]/layout.tsx
export default async function Layout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Promise<{ team: string }>
}) {
  const { team } = await params
}
app/dashboard/[team]/layout.js
export default async function Layout({ children, params }) {
  const { team } = await params
}
示例路由URLparams
app/dashboard/[team]/layout.js/dashboard/1Promise<{ team: '1' }>
app/shop/[tag]/[item]/layout.js/shop/1/2Promise<{ tag: '1', item: '2' }>
app/blog/[...slug]/layout.js/blog/1/2Promise<{ slug: ['1', '2'] }>
  • 由于 params prop 是一个 Promise。你必须使用 async/await 或 React 的 use 函数来访问这些值。
    • 在 14 及更早版本中,params 是一个同步 prop。为了帮助向后兼容,你在 Next.js 15 中仍然可以同步访问它,但此行为将来会被弃用。

布局 Props 辅助工具#

你可以使用 LayoutProps 为布局添加类型,从而获得强类型的 params 以及从目录结构推断出的命名插槽。LayoutProps 是一个全局可用的辅助工具。

app/dashboard/layout.tsx
export default function Layout(props: LayoutProps<'/dashboard'>) {
  return (
    <section>
      {props.children}
      
      
    </section>
  )
}

小知识:

  • 类型会在 next dev、next build 或 next typegen 期间生成。
  • 类型生成后,LayoutProps 辅助工具即可全局使用,无需导入。

根布局#

app 目录必须包含一个根布局,它是根 app 目录中最顶层的布局。通常,根布局是 app/layout.js。

app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>{children}</body>
    </html>
  )
}
app/layout.js
export default function RootLayout({ children }) {
  return (
    <html>
      <body>{children}</body>
    </html>
  )
}
  • 根布局必须定义 <html> 和 <body> 标签。
    • 你不应手动向根布局添加 <head> 标签,例如 <title> 和 <meta>。相反,你应该使用 Metadata API,它会自动处理流式传输和 <head> 元素去重等高级需求。
  • 你可以创建多个根布局。任何上方没有 layout.js 的布局都是根布局。两种常见做法:
    • 使用路由组,例如 app/(shop)/layout.js 和 app/(marketing)/layout.js
    • 省略 app/layout.js,使 app/dashboard/layout.js 和 app/blog/layout.js 等子目录中的布局各自成为其对应目录的根布局。
    • 跨多个根布局导航将导致整页加载(而非客户端导航)。
  • 根布局可以位于动态段之下,例如在使用 app/[lang]/layout.js 实现国际化时。根布局之前的动态段是根参数,可以通过 next/root-params 从任何 Server Component 中读取。

注意事项#

Request 对象#

布局在导航期间会缓存在客户端,以避免不必要的服务端请求。

布局不会重新渲染。它们可以被缓存和复用,从而在页面之间导航时避免不必要的计算。通过限制布局访问原始请求,Next.js 可以防止在布局中执行可能缓慢或开销较大的用户代码,否则这可能会对性能产生负面影响。

要访问请求对象,你可以在 Server Components 和函数中使用 headers 和 cookies API。

app/shop/layout.tsx
import { cookies } from 'next/headers'

export default async function Layout({ children }) {
  const cookieStore = await cookies()
  const theme = cookieStore.get('theme')
  return '...'
}
app/shop/layout.js
import { cookies } from 'next/headers'

export default async function Layout({ children }) {
  const cookieStore = await cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

查询参数#

布局在导航时不会重新渲染,因此无法访问搜索参数,否则这些参数会变得过期。

要访问更新后的查询参数,你可以使用页面的 searchParams prop,或者在 Client Component 中使用 useSearchParams hook 读取它们。由于 Client Component 会在导航时重新渲染,因此它们可以访问最新的查询参数。

app/ui/search.tsx
'use client'

import { useSearchParams } from 'next/navigation'

export default function Search() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  return '...'
}
app/ui/search.js
'use client'

import { useSearchParams } from 'next/navigation'

export default function Search() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  return '...'
}
app/shop/layout.tsx
import Search from '@/app/ui/search'

export default function Layout({ children }) {
  return (
    <>
      <Search />
      {children}
    </>
  )
}
app/shop/layout.js
import Search from '@/app/ui/search'

export default function Layout({ children }) {
  return (
    <>
      <Search />
      {children}
    </>
  )
}

Pathname#

布局在导航时不会重新渲染,因此无法访问 pathname,否则它会变得过期。

要访问当前 pathname,你可以在 Client Component 中使用 usePathname hook 读取它。由于 Client Component 会在导航期间重新渲染,因此它们可以访问最新的 pathname。

app/ui/breadcrumbs.tsx
'use client'

import { usePathname } from 'next/navigation'

// 简化的面包屑逻辑
export default function Breadcrumbs() {
  const pathname = usePathname()
  const segments = pathname.split('/')

  return (
    <nav>
      {segments.map((segment, index) => (
        <span key={index}>
          {' > '}
          {segment}
        </span>
      ))}
    </nav>
  )
}
app/ui/breadcrumbs.js
'use client'

import { usePathname } from 'next/navigation'

// 简化的面包屑逻辑
export default function Breadcrumbs() {
  const pathname = usePathname()
  const segments = pathname.split('/')

  return (
    <nav>
      {segments.map((segment, index) => (
        <span key={index}>
          {' > '}
          {segment}
        </span>
      ))}
    </nav>
  )
}
app/docs/layout.tsx
import { Breadcrumbs } from '@/app/ui/Breadcrumbs'

export default function Layout({ children }) {
  return (
    <>
      <Breadcrumbs />
      <main>{children}</main>
    </>
  )
}
app/docs/layout.js
import { Breadcrumbs } from '@/app/ui/Breadcrumbs'

export default function Layout({ children }) {
  return (
    <>
      <Breadcrumbs />
      <main>{children}</main>
    </>
  )
}

与 loading.js 的交互#

由于 loading.js 在组件层次结构中位于 layout.js 之下,因此它无法为布局本身的未缓存数据访问或运行时数据访问(例如调用 cookies()、headers() 或发起未缓存的 fetch)显示 fallback。

行为取决于是否启用了 Cache Components:

  • 未启用 Cache Components 时: 导航将阻塞直到布局渲染完成,loading.js 的 fallback 不会显示。
  • 启用 Cache Components 时: loading.js 被视为普通的 <Suspense> 边界,而不是特殊的可预取标记。布局中的未缓存数据访问或运行时数据访问必须显式包裹在其自己的 <Suspense> 边界中,否则 Next.js 会通过构建时错误引导你进行处理。静态外壳会立即流式传输,未缓存的内容在解析完成后替换进来。

在这两种情况下,要确保即时导航,可以:

  • 将布局中的运行时数据访问包裹在其自己的 <Suspense> 边界中,并提供 fallback。
  • 将未缓存的数据获取从 layout.js 移到 page.js,这样 loading.js 就可以显示 fallback。
app/dashboard/layout.tsx
import { Suspense } from 'react'
import { NavSkeleton } from './nav-skeleton'
import { DashboardNav } from './dashboard-nav'

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <Suspense fallback={<NavSkeleton />}>
        <DashboardNav />
      </Suspense>
      <main>{children}</main>
    </>
  )
}
app/dashboard/layout.js
import { Suspense } from 'react'
import { NavSkeleton } from './nav-skeleton'
import { DashboardNav } from './dashboard-nav'

export default function Layout({ children }) {
  return (
    <>
      <Suspense fallback={<NavSkeleton />}>
        <DashboardNav />
      </Suspense>
      <main>{children}</main>
    </>
  )
}

获取数据#

布局无法将数据传递给其 children。不过,你可以在一个路由中多次获取相同的数据,并使用 React 的 cache 对请求进行去重,而不会影响性能。

或者,在 Next.js 中使用 fetch 时,请求会自动去重。

app/lib/data.ts
export async function getUser(id: string) {
  const res = await fetch(`https://.../users/${id}`)
  return res.json()
}
app/dashboard/layout.tsx
import { getUser } from '@/app/lib/data'
import { UserName } from '@/app/ui/user-name'

export default async function Layout({ children }) {
  const user = await getUser('1')

  return (
    <>
      <nav>
        
        <UserName user={user.name} />
      </nav>
      {children}
    </>
  )
}
app/dashboard/layout.js
import { getUser } from '@/app/lib/data'
import { UserName } from '@/app/ui/user-name'

export default async function Layout({ children }) {
  const user = await getUser('1')

  return (
    <>
      <nav>
        
        <UserName user={user.name} />
      </nav>
      {children}
    </>
  )
}
app/dashboard/page.tsx
import { getUser } from '@/app/lib/data'
import { UserName } from '@/app/ui/user-name'

export default async function Page() {
  const user = await getUser('1')

  return (
    <div>
      <h1>Welcome {user.name}</h1>
    </div>
  )
}
app/dashboard/page.js
import { getUser } from '@/app/lib/data'
import { UserName } from '@/app/ui/user-name'

export default async function Page() {
  const user = await getUser('1')

  return (
    <div>
      <h1>Welcome {user.name}</h1>
    </div>
  )
}

访问子路由段#

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

app/ui/nav-link.tsx
'use client'

import Link from 'next/link'
import { useSelectedLayoutSegment } from 'next/navigation'

export default function NavLink({
  slug,
  children,
}: {
  slug: string
  children: React.ReactNode
}) {
  const segment = useSelectedLayoutSegment()
  const isActive = slug === segment

  return (
    <Link
      href={`/blog/${slug}`}
      // 根据链接是否处于活动状态更改样式
      style={{ fontWeight: isActive ? 'bold' : 'normal' }}
    >
      {children}
    </Link>
  )
}
app/ui/nav-link.js
'use client'

import Link from 'next/link'
import { useSelectedLayoutSegment } from 'next/navigation'

export default function NavLink({ slug, children }) {
  const segment = useSelectedLayoutSegment()
  const isActive = slug === segment

  return (
    <Link
      href={`/blog/${slug}`}
      style={{ fontWeight: isActive ? 'bold' : 'normal' }}
    >
      {children}
    </Link>
  )
}
app/blog/layout.tsx
import NavLink from '@/app/ui/nav-link'
import getPosts from './get-posts'

export default async function Layout({
  children,
}: {
  children: React.ReactNode
}) {
  const featuredPosts = await getPosts()
  return (
    <div>
      {featuredPosts.map((post) => (
        <div key={post.id}>
          <NavLink slug={post.slug}>{post.title}</NavLink>
        </div>
      ))}
      <div>{children}</div>
    </div>
  )
}
app/blog/layout.js
import NavLink from '@/app/ui/nav-link'
import getPosts from './get-posts'

export default async function Layout({ children }) {
  const featuredPosts = await getPosts()
  return (
    <div>
      {featuredPosts.map((post) => (
        <div key={post.id}>
          <NavLink slug={post.slug}>{post.title}</NavLink>
        </div>
      ))}
      <div>{children}</div>
    </div>
  )
}

示例#

Metadata#

你可以使用 metadata 对象或 generateMetadata 函数来修改 <head> HTML 元素,例如 title 和 meta。

app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Next.js',
}

export default function Layout({ children }: { children: React.ReactNode }) {
  return '...'
}
app/layout.js
export const metadata = {
  title: 'Next.js',
}

export default function Layout({ children }) {
  return '...'
}

小知识: 你不应手动向根布局添加 <head> 标签,例如 <title> 和 <meta>。相反,应使用 Metadata API,它会自动处理流式传输和 <head> 元素去重等高级需求。

活动导航链接#

你可以使用 usePathname hook 来判断导航链接是否处于活动状态。

由于 usePathname 是一个客户端 hook,你需要将导航链接提取到一个 Client Component 中,然后将其导入到布局中:

app/ui/nav-links.tsx
'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/ui/nav-links.js
'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
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>
  )
}
app/layout.js
import { NavLinks } from '@/app/ui/nav-links'

export default function Layout({ children }) {
  return (
    <html lang="en">
      <body>
        <NavLinks />
        <main>{children}</main>
      </body>
    </html>
  )
}

基于 params 显示内容#

使用动态路由段,你可以根据 params prop 显示或获取特定内容。

app/dashboard/layout.tsx
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>
  )
}
app/dashboard/layout.js
export default async function DashboardLayout({ children, params }) {
  const { team } = await params

  return (
    <section>
      <header>
        <h1>Welcome to {team}'s Dashboard</h1>
      </header>
      <main>{children}</main>
    </section>
  )
}

在 Client Component 中读取 params#

要在 Client Component(不能是 async)中使用 params,你可以使用 React 的 use 函数来读取这个 Promise:

app/page.tsx
'use client'

import { use } from 'react'

export default function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = use(params)
}
app/page.js
'use client'

import { use } from 'react'

export default function Page({ params }) {
  const { slug } = use(params)
}

版本历史#

版本变更
v15.0.0-RCparams 现在是一个 Promise。可使用 codemod。
v13.0.0引入 layout。
Next.js 中文网