layout.js

版面配置 (Layout) 是路由之間共享的使用者介面。

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

根版面配置 (Root Layout) 是根目錄 app 中最頂層的版面配置，用於定義 <html> 和 <body> 標籤以及其他全域共享的使用者介面。

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

屬性 (Props)

`children` (必填)

版面配置元件應接受並使用 children 屬性。在渲染過程中，children 將被填入該版面配置所包裝的路由區段。這些主要會是子版面配置 (Layout) (如果存在) 或頁面 (Page) 的元件，但也可能是其他特殊檔案，例如適用的載入 (Loading) 或錯誤 (Error)。

`params` (選填)

從根區段到該版面配置的動態路由參數 (dynamic route parameters) 物件。

範例	URL	`params`
`app/dashboard/[team]/layout.js`	`/dashboard/1`	`{ team: '1' }`
`app/shop/[tag]/[item]/layout.js`	`/shop/1/2`	`{ tag: '1', item: '2' }`
`app/blog/[...slug]/layout.js`	`/blog/1/2`	`{ slug: ['1', '2'] }`

例如：

export default function ShopLayout({
  children,
  params,
}: {
  children: React.ReactNode
  params: {
    tag: string
    item: string
  }
}) {
  // URL -> /shop/shoes/nike-air-max-97
  // `params` -> { tag: 'shoes', item: 'nike-air-max-97' }
  return <section>{children}</section>
}

須知事項

版面配置不會接收 `searchParams`

與頁面 (Pages) 不同，版面配置元件不會接收 searchParams 屬性。這是因為共享版面配置在導航期間不會重新渲染，這可能導致導航之間的 searchParams 過時。

使用客戶端導航時，Next.js 會自動僅渲染兩個路由之間共享版面配置下方的頁面部分。

例如，在以下目錄結構中，dashboard/layout.tsx 是 /dashboard/settings 和 /dashboard/analytics 的共享版面配置：

檔案結構顯示 dashboard 資料夾嵌套了 layout.tsx 檔案，以及 settings 和 analytics 資料夾各自擁有其頁面

從 /dashboard/settings 導航到 /dashboard/analytics 時，/dashboard/analytics 中的 page.tsx 會在伺服器上重新渲染，而 dashboard/layout.tsx 不會重新渲染，因為它是兩個路由之間共享的使用者介面。

這種效能優化使得共享版面配置的頁面之間的導航更快，因為只需執行頁面的資料獲取和渲染，而不是整個可能包含需要獲取自身資料的共享版面配置的路由。

由於 dashboard/layout.tsx 不會重新渲染，版面配置伺服器元件中的 searchParams 屬性在導航後可能會過時。

請改用頁面的 searchParams 屬性或在客戶端元件中使用 useSearchParams 鉤子，這些會在客戶端重新渲染時使用最新的 searchParams。

根版面配置 (Root Layouts)

app 目錄必須包含一個根 app/layout.js。
根版面配置必須定義 <html> 和 <body> 標籤。
- 您不應手動將 <head> 標籤 (如 <title> 和 <meta>) 添加到根版面配置中。相反，您應使用元資料 API (Metadata API)，它會自動處理進階需求，例如串流和去重複 <head> 元素。
您可以使用路由群組 (route groups) 來建立多個根版面配置。
- 在多個根版面配置之間導航將導致完整頁面載入 (與客戶端導航相反)。例如，從使用 app/(shop)/layout.js 的 /cart 導航到使用 app/(marketing)/layout.js 的 /blog 將導致完整頁面載入。這僅適用於多個根版面配置。

版本歷史

版本	變更
`v13.0.0`	引入 `layout`。

屬性 (Props)

children (必填)

params (選填)