平行路由 (Parallel Routes)

平行路由 (Parallel Routes) 讓您可以在同一佈局中同時或有條件地渲染一個或多個頁面。這對於應用程式中高度動態的部分非常有用，例如社交網站上的儀表板和動態訊息。

舉例來說，考慮一個儀表板，您可以使用平行路由同時渲染 team 和 analytics 頁面：

插槽 (Slots)

平行路由是透過命名的插槽 (slots) 來建立的。插槽使用 @folder 慣例定義。例如，以下檔案結構定義了兩個插槽：@analytics 和 @team：

插槽會作為 props 傳遞給共享的父佈局。對於上面的例子，app/layout.js 中的元件現在接受 @analytics 和 @team 插槽 props，並可以與 children prop 一起平行渲染：

export default function Layout({
  children,
  team,
  analytics,
}: {
  children: React.ReactNode
  analytics: React.ReactNode
  team: React.ReactNode
}) {
  return (
    <>
      {children}
      {team}
      {analytics}
    </>
  )
}

然而，插槽不是路由區段 (route segments)，也不會影響 URL 結構。例如，對於 /@analytics/views，URL 會是 /views，因為 @analytics 是一個插槽。

須知：

children prop 是一個隱含的插槽，不需要映射到資料夾。這意味著 app/page.js 等同於 app/@children/page.js。

活動狀態與導航

預設情況下，Next.js 會追蹤每個插槽的活動狀態 (或子頁面)。但插槽中渲染的內容取決於導航類型：

軟導航 (Soft Navigation)：在客戶端導航期間，Next.js 會執行部分渲染 (partial render)，變更插槽內的子頁面，同時保持其他插槽的活動子頁面，即使它們與當前 URL 不匹配。
硬導航 (Hard Navigation)：在完整頁面載入 (瀏覽器重新整理) 後，Next.js 無法確定與當前 URL 不匹配的插槽的活動狀態。相反，它會為不匹配的插槽渲染 default.js 檔案，如果 default.js 不存在，則渲染 404。

須知：

對於不匹配路由的 404 有助於確保您不會意外地在不該渲染平行路由的頁面上渲染它。

`default.js`

您可以定義一個 default.js 檔案，作為初始載入或完整頁面重新載入時不匹配插槽的後備渲染。

考慮以下資料夾結構。@team 插槽有一個 /settings 頁面，但 @analytics 沒有。

當導航到 /settings 時，@team 插槽會渲染 /settings 頁面，同時保持 @analytics 插槽當前活動的頁面。

重新整理後，Next.js 會為 @analytics 渲染 default.js。如果 default.js 不存在，則會渲染 404。

此外，由於 children 是一個隱含的插槽，您也需要建立一個 default.js 檔案，以便在 Next.js 無法恢復父頁面的活動狀態時為 children 渲染後備內容。

`useSelectedLayoutSegment(s)`

useSelectedLayoutSegment 和 useSelectedLayoutSegments 都接受一個 parallelRoutesKey 參數，允許您讀取插槽內的活動路由區段。

'use client'

import { useSelectedLayoutSegment } from 'next/navigation'

export default function Layout({ auth }: { auth: React.ReactNode }) {
  const loginSegment = useSelectedLayoutSegment('auth')
  // ...
}

當用戶導航到 app/@auth/login (或 URL 列中的 /login) 時，loginSegment 會等於字串 "login"。

範例

條件式路由

您可以使用平行路由根據特定條件 (例如用戶角色) 有條件地渲染路由。例如，為 /admin 或 /user 角色渲染不同的儀表板頁面：

import { checkUserRole } from '@/lib/auth'

export default function Layout({
  user,
  admin,
}: {
  user: React.ReactNode
  admin: React.ReactNode
}) {
  const role = checkUserRole()
  return <>{role === 'admin' ? admin : user}</>
}

標籤群組 (Tab Groups)

您可以在插槽內新增一個 layout，讓用戶可以獨立導航該插槽。這對於建立標籤頁非常有用。

例如，@analytics 插槽有兩個子頁面：/page-views 和 /visitors。

在 @analytics 內，建立一個 layout 檔案，以在兩個頁面之間共享標籤：

import Link from 'next/link'

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <nav>
        <Link href="/page-views">Page Views</Link>
        <Link href="/visitors">Visitors</Link>
      </nav>
      <div>{children}</div>
    </>
  )
}

模態框 (Modals)

平行路由可以與攔截路由 (Intercepting Routes) 一起使用來建立模態框。這讓您可以解決建立模態框時的常見挑戰，例如：

透過 URL 共享模態框內容。
在頁面重新整理時保留上下文，而不是關閉模態框。
在向後導航時關閉模態框，而不是返回上一條路由。
在向前導航時重新開啟模態框。

考慮以下 UI 模式，用戶可以透過客戶端導航從佈局中開啟登入模態框，或存取獨立的 /login 頁面：

要實現此模式，首先建立一個 /login 路由，渲染您的主要登入頁面。

import { Login } from '@/app/ui/login'

export default function Page() {
  return <Login />
}

然後，在 @auth 插槽內，新增一個 default.js 檔案，返回 null。這確保了模態框在不活動時不會被渲染。

export default function Default() {
  return null
}

在您的 @auth 插槽內，透過更新 /(.)login 資料夾來攔截 /login 路由。將 <Modal> 元件及其子元件匯入到 /(.)login/page.tsx 檔案中：

import { Modal } from '@/app/ui/modal'
import { Login } from '@/app/ui/login'

export default function Page() {
  return (
    <Modal>
      <Login />
    </Modal>
  )
}

須知：

用於攔截路由的慣例 (例如 (.)) 取決於您的檔案系統結構。請參閱攔截路由慣例。

透過將 <Modal> 功能與模態框內容 (<Login>) 分開，您可以確保模態框內的任何內容 (例如表單) 都是伺服器元件。請參閱交錯客戶端和伺服器元件以獲取更多資訊。

開啟模態框

現在，您可以利用 Next.js 路由器來開啟和關閉模態框。這確保了模態框開啟時 URL 正確更新，以及在向後和向前導航時的行為。

要開啟模態框，將 @auth 插槽作為 prop 傳遞給父佈局，並與 children prop 一起渲染。

import Link from 'next/link'

export default function Layout({
  auth,
  children,
}: {
  auth: React.ReactNode
  children: React.ReactNode
}) {
  return (
    <>
      <nav>
        <Link href="/login">Open modal</Link>
      </nav>
      <div>{auth}</div>
      <div>{children}</div>
    </>
  )
}

當用戶點擊 <Link> 時，模態框會開啟，而不是導航到 /login 頁面。然而，在重新整理或初始載入時，導航到 /login 會將用戶帶到主要登入頁面。

關閉模態框

您可以透過呼叫 router.back() 或使用 Link 元件來關閉模態框。

'use client'

import { useRouter } from 'next/navigation'

export function Modal({ children }: { children: React.ReactNode }) {
  const router = useRouter()

  return (
    <>
      <button
        onClick={() => {
          router.back()
        }}
      >
        Close modal
      </button>
      <div>{children}</div>
    </>
  )
}

當使用 Link 元件導航離開不應再渲染 @auth 插槽的頁面時，我們使用一個返回 null 的萬用路由 (catch-all route)。

import Link from 'next/link'

export function Modal({ children }: { children: React.ReactNode }) {
  return (
    <>
      <Link href="/">Close modal</Link>
      <div>{children}</div>
    </>
  )
}

須知：

我們在 @auth 插槽中使用萬用路由來關閉模態框，是因為活動狀態與導航中描述的行為。由於客戶端導航到不再匹配插槽的路由時，插槽會保持可見，我們需要將插槽匹配到一個返回 null 的路由來關閉模態框。

其他範例可能包括在相簿中開啟照片模態框，同時擁有專用的 /photo/[id] 頁面，或在側邊模態框中開啟購物車。

查看範例了解如何使用攔截和平行路由實現模態框。

載入與錯誤 UI

平行路由可以獨立串流，讓您為每條路由定義獨立的錯誤和載入狀態：

請參閱載入 UI 和錯誤處理文件以獲取更多資訊。

default.js

關於 default.js 檔案的 API 參考文件

default.js

On this page