頁面與佈局

建議先閱讀路由基礎和定義路由頁面再繼續。

特殊檔案 layout.js、page.js 和 template.js 可讓您為路由建立使用者介面。本頁將指導您如何使用這些特殊檔案及其適用時機。

頁面

頁面是路由專屬的使用者介面。您可以透過從 page.js 檔案預設匯出元件來定義頁面。

例如，要建立 index 頁面，請在 app 目錄中新增 page.js 檔案：

// `app/page.tsx` 是 `/` URL 的使用者介面
export default function Page() {
  return <h1>Hello, Home page!</h1>
}

接著，要建立更多頁面，請新增一個資料夾並在其中新增 page.js 檔案。例如，要為 /dashboard 路由建立頁面，請建立名為 dashboard 的新資料夾，並在其中新增 page.js 檔案：

// `app/dashboard/page.tsx` 是 `/dashboard` URL 的使用者介面
export default function Page() {
  return <h1>Hello, Dashboard Page!</h1>
}

須知事項：

頁面可使用 .js、.jsx 或 .tsx 副檔名。

頁面始終是路由子樹的葉節點。

需要 page.js 檔案才能讓路由區段公開存取。

頁面預設為伺服器元件 (Server Components)，但可設為客戶端元件 (Client Component)。

頁面可擷取資料。詳情請參閱資料擷取章節。

佈局

佈局是多個路由之間共享的使用者介面。在導航時，佈局會保留狀態、保持互動性且不會重新渲染。佈局也可嵌套。

您可以透過從 layout.js 檔案預設匯出 React 元件來定義佈局。該元件應接受 children 屬性，在渲染時會填入子佈局（如果存在）或頁面。

例如，以下佈局將與 /dashboard 和 /dashboard/settings 頁面共享：

export default function DashboardLayout({
  children, // 將是頁面或嵌套佈局
}: {
  children: React.ReactNode
}) {
  return (
    <section>
      {/* 在此包含共享 UI，例如標頭或側邊欄 */}
      <nav></nav>

      {children}
    </section>
  )
}

根佈局 (必要)

根佈局定義於 app 目錄的頂層，適用於所有路由。此佈局是必要的，且必須包含 html 和 body 標籤，讓您可以修改從伺服器返回的初始 HTML。

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 檔案：

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 Component)。

佈局可擷取資料。詳情請參閱資料擷取章節。

無法在父佈局與其子元件之間傳遞資料。不過，您可以在路由中多次擷取相同資料，React 會自動去重複請求而不影響效能。

佈局無法存取其下方的路由區段。若要存取所有路由區段，可在客戶端元件中使用 useSelectedLayoutSegment 或 useSelectedLayoutSegments。

您可以使用路由群組 (Route Groups) 來選擇性地讓特定路由區段加入或退出共享佈局。

您可以使用路由群組 (Route Groups) 建立多個根佈局。請參閱此範例。

從 pages 目錄遷移： 根佈局取代了 _app.js 和 _document.js 檔案。查看遷移指南。

模板

模板與佈局類似，都會包裹每個子佈局或頁面。不同之處在於，佈局會跨路由保留狀態，而模板會在導航時為每個子元件建立新實例。這意味著當使用者在共享模板的路由之間導航時，會掛載元件的新實例、重新建立 DOM 元素、不會保留狀態，且會重新同步效果。

在某些情況下，您可能需要這些特定行為，此時模板會比佈局更適合。例如：

依賴 useEffect 的功能（例如記錄頁面瀏覽）和 useState（例如每頁回饋表單）。
變更預設框架行為。例如，佈局內的 Suspense Boundaries 僅在首次載入佈局時顯示後備內容，切換頁面時不會顯示。對於模板，每次導航都會顯示後備內容。

您可以透過從 template.js 檔案預設匯出 React 元件來定義模板。該元件應接受 children 屬性。

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

在嵌套方面，template.js 會在佈局與其子元件之間渲染。以下是簡化的輸出：

輸出

<Layout>
  {/* 注意模板具有唯一鍵。 */}
  <Template key={routeParam}>{children}</Template>
</Layout>

元數據

在 app 目錄中，您可以使用元數據 API (Metadata APIs) 修改 <head> HTML 元素，例如 title 和 meta。

您可以透過在 layout.js 或 page.js 檔案中匯出 metadata 物件或 generateMetadata 函式來定義元數據。

import { Metadata } from 'next'

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

export default function Page() {
  return '...'
}

須知事項：您不應手動新增 <head> 標籤（例如 <title> 和 <meta>）至根佈局。相反地，您應使用元數據 API (Metadata API)，它會自動處理進階需求，例如串流和去重複 <head> 元素。

在 API 參考中了解更多可用的元數據選項。

頁面

佈局

根佈局 (必要)

嵌套佈局

模板

元數據

On this page