NNext.js 中文网 GitHub

并行路由

在同一视图中同时渲染一个或多个可以独立导航的页面。适用于高度动态应用程序的一种模式。

并行路由允许你在同一布局中同时或按条件渲染一个或多个页面。它们适用于应用中高度动态的部分,例如仪表盘和社交网站的信息流。

例如,以仪表盘为例,你可以使用并行路由同时渲染 team 和 analytics 页面:

约定#

插槽#

并行路由使用命名插槽创建。插槽通过 @folder 约定定义。例如,以下文件结构定义了两个插槽:@analytics 和 @team:

插槽作为 props 传递给共享的父布局。对于上面的示例,app/layout.js 中的组件现在接受 @analytics 和 @team 插槽 props,并可以与 children prop 一起并行渲染它们:

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

不过,插槽不是路由段,不会影响 URL 结构。例如,对于 /@analytics/views,URL 将是 /views,因为 @analytics 是一个插槽。插槽与常规的 Page 组件组合,形成与该路由段关联的最终页面。因此,你不能在同一路由段层级拥有分别 prerendered 和 dynamically rendered 的插槽。如果某个插槽是动态的,该层级的所有插槽都必须是动态的。

小知识:

  • 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 是隐式插槽,当 Next.js 无法恢复父页面的活动状态时,你还需要创建一个 default.js 文件来为 children 渲染回退内容。

行为#

默认情况下,Next.js 会跟踪每个插槽的活动 state(或子页面)。不过,插槽中渲染的内容取决于导航的类型:

  • 软导航(Soft Navigation):在客户端导航期间,Next.js 会执行部分渲染,更改插槽内的子页面,同时保持其他插槽的活动子页面,即使它们与当前 URL 不匹配。
  • 硬导航:整页加载(浏览器刷新)后,Next.js 无法确定与当前 URL 不匹配的插槽的活动状态。相反,它将为未匹配的插槽渲染 default.js 文件,如果 default.js 不存在,则渲染 404。

小知识:

  • 未匹配路由的 404 有助于确保你不会意外地在非目标页面上渲染并行路由。

示例#

使用 useSelectedLayoutSegment(s)#

useSelectedLayoutSegment 和 useSelectedLayoutSegments 都接受一个 parallelRouteKey 参数,使你可以读取插槽内的活动路由段。

app/layout.tsx
'use client'

import { useSelectedLayoutSegment } from 'next/navigation'

export default function Layout({ auth }: { auth: React.ReactNode }) {
  const loginSegment = useSelectedLayoutSegment('auth')
  // ...
}
app/layout.js
'use client'

import { useSelectedLayoutSegment } from 'next/navigation'

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

当用户导航到 app/@auth/login(或 URL 栏中的 /login)时,loginSegment 将等于字符串 "login"。

条件路由#

你可以使用并行路由根据特定条件(例如用户角色)按条件渲染路由。例如,为 /admin 或 /user 角色渲染不同的仪表盘页面:

app/dashboard/layout.tsx
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
}
app/dashboard/layout.js
import { checkUserRole } from '@/lib/auth'

export default function Layout({ user, admin }) {
  const role = checkUserRole()
  return role === 'admin' ? admin : user
}

两个插槽都会在服务器上渲染,无论布局返回哪一个。条件决定的是用户看到什么,而不是运行什么:@admin/page.js 会为每个用户执行其数据获取,其输出会包含在发送给浏览器的响应中。请在每个插槽的页面内或你的 Data Access Layer 中进行授权:

app/dashboard/@admin/page.tsx
import { getAdminStats } from '@/lib/dal'

export default async function AdminPage() {
  const stats = await getAdminStats()
  return <Stats stats={stats} />
}
app/dashboard/@admin/page.js
import { getAdminStats } from '@/lib/dal'

export default async function AdminPage() {
  const stats = await getAdminStats()
  return <Stats stats={stats} />
}

标签组#

你可以在插槽内添加 layout,以允许用户独立导航该插槽。这对于创建标签页很有用。

例如,@analytics 插槽有两个子页面:/page-views 和 /visitors。

在 @analytics 中,创建一个 layout 文件以在两个页面之间共享标签页:

app/@analytics/layout.tsx
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>
    </>
  )
}
app/@analytics/layout.js
import Link from 'next/link'

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

模态框#

并行路由可以与拦截路由一起使用,以创建支持深层链接的模态框。这使你能够解决构建模态框时的常见难题,例如:

  • 使模态框内容可通过 URL 共享。
  • 页面刷新时保留上下文,而不是关闭模态框。
  • 向后导航时关闭模态框,而不是转到上一个路由。
  • 向前导航时重新打开模态框。

考虑以下 UI 模式,用户可以使用客户端导航从布局中打开登录模态框,或访问单独的 /login 页面:

要实现此模式,首先创建一个 /login 路由来渲染你的主登录页面。

app/login/page.tsx
import { Login } from '@/app/ui/login'

export default function Page() {
  return <Login />
}
app/login/page.js
import { Login } from '@/app/ui/login'

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

然后,在 @auth 插槽内,添加一个返回 null 的 default.js 文件。这可确保模态框在未激活时不会被渲染。

app/@auth/default.tsx
export default function Default() {
  return null
}
app/@auth/default.js
export default function Default() {
  return null
}

在 @auth 插槽内,通过将 <Modal> 组件及其子元素导入 @auth/(.)login/page.tsx 文件,并将文件夹名称更新为 /@auth/(.)login/page.tsx,来拦截 /login 路由。

app/@auth/(.)login/page.tsx
import { Modal } from '@/app/ui/modal'
import { Login } from '@/app/ui/login'

export default function Page() {
  return (
    <Modal>
      <Login />
    </Modal>
  )
}
app/@auth/(.)login/page.js
import { Modal } from '@/app/ui/modal'
import { Login } from '@/app/ui/login'

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

小知识:

  • 约定 (.) 用于拦截路由。有关更多信息,请参阅拦截路由文档。
  • 通过将 <Modal> 功能与模态框内容(<Login>)分离,你可以确保模态框内的任何内容(例如表单)都是 Server Components。有关更多信息,请参阅交错使用 Client 和 Server Components。

打开模态框#

现在,你可以利用 Next.js router 来打开和关闭模态框。这可确保在模态框打开时以及向前或向后导航时,URL 都能正确更新。

要打开模态框,将 @auth 插槽作为 prop 传递给父布局,并与 children prop 一起渲染。

app/layout.tsx
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>
    </>
  )
}
app/layout.js
import Link from 'next/link'

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

当用户点击 <Link> 时,模态框将打开,而不是导航到 /login 页面。不过,在刷新或初始加载时,导航到 /login 将把用户带到主登录页面。

关闭模态框#

你可以通过调用 router.back() 或使用 Link 组件来关闭模态框。

app/ui/modal.tsx
'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>
    </>
  )
}
app/ui/modal.js
'use client'

import { useRouter } from 'next/navigation'

export function Modal({ children }) {
  const router = useRouter()

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

当使用 Link 组件从不应再渲染 @auth 插槽的页面导航离开时,我们需要确保并行路由匹配到返回 null 的组件。例如,当导航回根页面时,我们创建一个 @auth/page.tsx 组件:

app/ui/modal.tsx
import Link from 'next/link'

export function Modal({ children }: { children: React.ReactNode }) {
  return (
    <>
      <Link href="/">Close modal</Link>
      <div>{children}</div>
    </>
  )
}
app/ui/modal.js
import Link from 'next/link'

export function Modal({ children }) {
  return (
    <>
      <Link href="/">Close modal</Link>
      <div>{children}</div>
    </>
  )
}
app/@auth/page.tsx
export default function Page() {
  return null
}
app/@auth/page.js
export default function Page() {
  return null
}

或者,如果要导航到任何其他页面(例如 /foo、/foo/bar 等),可以使用全捕获插槽:

app/@auth/[...catchAll]/page.tsx
export default function CatchAll() {
  return null
}
app/@auth/[...catchAll]/page.js
export default function CatchAll() {
  return null
}

小知识:

  • 我们在 @auth 插槽中使用全捕获路由来关闭模态框,这是由并行路由的行为决定的。由于客户端导航到不再匹配插槽的路由时该插槽仍会保持可见,我们需要将该插槽匹配到返回 null 的路由,以关闭模态框。
  • 其他示例包括在画廊中打开照片模态框同时也有专门的 /photo/[id] 页面,或在侧边模态框中打开购物车。
  • 查看一个使用拦截路由和并行路由实现模态框的示例。

加载和错误 UI#

并行路由可以独立流式传输,使你可以为每条路由定义独立的错误和加载状态:

有关更多信息,请参阅 Loading UI 和 错误处理 文档。

Next.js 中文网