navigation
使用 navigation 函数将运行时工作推迟到用户导航时执行。
调用 await navigation() 会使其下方的运行时工作不进入 App Shell 和按链接预取。这些工作会在用户导航时运行,而最近的 <Suspense> 边界的 fallback 则会在预取的输出中渲染。
对于生成成本高且应等到导航时才生成的可复用内容,请使用 navigation()。静态预渲染仍会将这些内容包含在其输出中,因此它们可能出现在静态预取中。
用法#
该函数需要 Cache Components,否则会抛出异常。它适用于使用 Partial Prefetching 的路由,你可以通过采用 Partial Prefetching 全局启用,或逐个路由启用。
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
export default nextConfig启用 Partial Prefetching 后,Next.js 会在客户端导航之前和期间分阶段加载服务端渲染的输出。以下是路由的导航阶段:
- 默认的
<Link>会加载 App Shell,其中包含路由中不依赖 URL 的部分。 - 可选的
<Link prefetch={true}>还可以加载依赖该链接 URL 的内容。 - 当用户点击该链接时,导航会渲染路由的其余部分。
在运行时渲染期间,等待 navigation() 会使内容不进入 App Shell 和按链接预取,因此它会在导航时渲染。静态预渲染仍然可以包含该内容。
在不启用 Partial Prefetching 的情况下,navigation() 仍会为默认的 <Link> 推迟内容,但 <Link prefetch={true}> 会获取整个路由(包括被推迟的内容),与导航一样。
要使内容不进入 App Shell,但仍包含在按链接预取中,请使用 prefetch()。
小知识:
navigation()只推迟一个子树。要跨整个路由要求静态 App Shell 和静态按链接预取,请使用ensureStatic = 'prefetch'。有关完整示例,请参阅保持页面为静态。
navigation() 之上的所有内容都可以在 App Shell 或按链接预取中渲染,而其下的所有内容都要等待导航。推迟作用的范围仅限于等待它的组件及其下方的树:同级分支保持其现有行为。请将其放在要推迟的代码之上,并用 <Suspense> 包裹该组件:
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, navigation } from 'next/cache'
export default function Page({ params }: PageProps<'/post/[slug]'>) {
return (
<>
<Suspense fallback={<p>Loading post...</p>}>
<PostBody params={params} />
</Suspense>
<Suspense fallback={<p>Loading comments...</p>}>
<Comments params={params} />
</Suspense>
</>
)
}
async function Comments({ params }: { params: Promise<{ slug: string }> }) {
await navigation() // 下方的运行时工作在导航时渲染
const { slug } = await params
const sort = (await cookies()).get('comment-sort')?.value ?? 'newest'
const items = await getComments(slug, sort)
return <CommentList items={items} />
}
async function getComments(slug: string, sort: string) {
'use cache'
cacheLife('hours')
return db.comments.list({ slug, sort })
}import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, navigation } from 'next/cache'
export default function Page({ params }) {
return (
<>
<Suspense fallback={<p>Loading post...</p>}>
<PostBody params={params} />
</Suspense>
<Suspense fallback={<p>Loading comments...</p>}>
<Comments params={params} />
</Suspense>
</>
)
}
async function Comments({ params }) {
await navigation() // 下方的运行时工作在导航时渲染
const { slug } = await params
const sort = (await cookies()).get('comment-sort')?.value ?? 'newest'
const items = await getComments(slug, sort)
return <CommentList items={items} />
}
async function getComments(slug, sort) {
'use cache'
cacheLife('hours')
return db.comments.list({ slug, sort })
}评论是按 slug 获取的,因此预取它们会占用一次按链接预取。在数据访问之前等待 navigation() 会使它们不进入预取,从而当用户导航时才会渲染。
slug 和 cookie 都在 navigation() 下方读取并作为参数传递,因此 getComments 会按帖子和排序顺序缓存,而不是按访问者缓存。当被推迟的内容渲染时,URL 已经解析完成,因此 params 在 navigation() 下方可用。
将该指令放在其下方调用的函数上,如此处的 getComments。不允许在缓存作用域内等待 navigation(),例如 use cache 或 use cache: private。
navigation() 与 connection() 的区别#
connection() 函数会等待真实请求。它会将后面的代码排除在预渲染和预取之外,使这些工作依赖于请求。
等待 navigation() 会将后面的代码排除在路由预取之外。它会在用户导航时兑现,而不会使这些工作依赖于请求。因此,在 await navigation() 之后调用的函数可以使用 "use cache",并在预取期间不生成结果的情况下保持其缓存生命周期。
当工作必须针对真实请求运行时,请使用 connection()。当工作可复用但应等到用户导航时,请使用 navigation()。
何时使用#
当其下方的内容生成成本高且不应由任何预取生成时,请使用 navigation()。
运行时 App Shell 和运行时按链接预取都不会运行该代码,因此其上游请求直到用户导航时才会发出。
不让内容进入缓存也会使其不进入预取,但会失去其缓存生命周期。
使用 navigation() 时,内容可以通过 use cache 进行缓存、指定生命周期,并推迟到导航时。给它设置五分钟或更长的 stale 时间,客户端路由器会在用户首次导航进入该路由后复用它。如果低于该时间,较短的生命周期会使其不进入 App Shell,因此每次导航都会重新获取它。
保持路由的预取为静态#
当对 cookies()、headers()、params 和 searchParams 的每次读取都位于 navigation() 下方时,预取所触发的预渲染无法生成超过构建时已生成的静态输出的内容,因此预取将直接由该输出提供。以这种方式构造路由是一种可选优化:静态响应可以缓存在 CDN 中,因此指向该路由的链接完全不消耗服务器 CPU。
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { navigation } from 'next/cache'
export default function Page() {
return (
<>
<FeedHeader />
<Suspense fallback={<p>Loading stories...</p>}>
<Stories />
</Suspense>
</>
)
}
async function Stories() {
await navigation()
const topic = (await cookies()).get('topic')?.value ?? 'all'
return <StoryList items={await getStories(topic)} />
}小知识#
- 该函数对页面的初始加载没有影响。
- 在
navigation()下方读取cookies()或headers()不会使路由的预取按请求渲染,因此它们仍可以由静态输出提供。这些访问会被忽略,因为它们在预取中本来也不会得到解析。 - 在
<Suspense>边界之外调用会在开发环境中显示一条 Instant Insight。完全预渲染的路由不受影响,但该洞察会指出:如果路由之后需要运行时渲染,该调用会在没有 fallback 的情况下推迟内容。 - 在
use cache、use cache: private、unstable_cache()、after()、generateStaticParams或 Client Component 中调用会抛出异常。
参考#
类型#
function navigation(): Promise<void>参数#
- 该函数不接受任何参数。
返回值#
一个 Promise<void>。它不供消费使用。
版本历史#
| 版本 | 变更 |
|---|---|
v16.4.0 | 引入 navigation,取代早期 canary 版本中使用的 unstable_navigation 名称。 |