平行路由 (Parallel Routes)

平行路由 (Parallel Routes) 允許您在同一佈局中同時或有條件地渲染一個或多個頁面。這對於應用中高度動態的區塊非常有用，例如社交網站的儀表板和動態消息。

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

慣例

插槽 (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}
    </>
  )
}

然而，插槽不是路由區段，不會影響 URL 結構。例如，對於 /@analytics/views，URL 會是 /views，因為 @analytics 是一個插槽。插槽與常規的頁面元件結合，形成與路由區段關聯的最終頁面。因此，您無法在同一路由區段級別同時擁有獨立的靜態和動態插槽。如果一個插槽是動態的，該級別的所有插槽都必須是動態的。

須知：

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

`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 提供後備渲染。

行為

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

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

須知：

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

範例

使用 `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 的元件。例如，當導航回根頁面時，我們建立一個 @auth/page.tsx 元件：

import Link from 'next/link'

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

或者，如果導航到任何其他頁面（例如 /foo、/foo/bar 等），您可以使用萬用插槽：

export default function CatchAll() {
  return null
}

須知：

我們在 @auth 插槽中使用萬用路由來關閉模態框，因為平行路由的行為(#behavior)。由於客戶端導航到不再匹配插槽的路由時，插槽仍會保持可見，我們需要將插槽匹配到一個返回 null 的路由以關閉模態框。

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

查看範例了解使用攔截和平行路由的模態框。

載入與錯誤 UI

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

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

default.js

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

default.js

On this page