Next.js 如何使用 Activity 保留 UI 状态
了解 React 的 Activity 组件如何在 Next.js 中跨导航保留 UI 状态,以及如何控制重置的内容。
小知识: 本指南假定已启用 Cache Components。可通过在 Next 配置文件中设置
cacheComponents: true来启用它。
在 Cache Components 之前,要跨导航保留页面级状态需要一些变通方法,例如将状态提升到共享布局或使用外部存储。有了 Cache Components,Next.js 开箱即用地保留状态和 DOM。
Next.js 不会在导航时卸载页面,而是使用 React 的 <Activity> 组件将它们隐藏。Activity 将 DOM 保留在文档中(通过 display: none 隐藏),因此 React 状态和 DOM 状态都会保留:表单草稿、滚动位置、展开的 <details> 元素、视频播放进度等等。
Next.js 最多保留 3 个路由。超过该数量后,最早的路由会被淘汰并重新渲染。
小知识: 将
useRouter().bfcacheId用作 Reactkey:单个<Fragment key={bfcacheId}>会在 push 或 replace 导航时(包括<Link>点击和router.push/router.replace)重置整个子树,同时仍在浏览器前进/后退时恢复状态。bfcacheId主要是一个迁移工具。对于新代码,优先使用下面针对各模式的重置方法。
选择要保留的内容#
Activity 默认保留所有组件状态和 DOM 状态。是否保留或重置某项状态取决于用户如何使用 UI。下面的示例展示了你可以将这些模式应用于其他具有相同状态或清理需求的组件。
可展开 UI(下拉菜单、手风琴、面板)#
当用户离开后又返回时,Activity 会保留可展开元素的打开/关闭状态。
何时保留: 带有展开部分的侧边栏、FAQ 手风琴或筛选面板。用户有意设置了视图,恢复它可以避免重复操作。
何时重置: 由按钮点击触发的下拉菜单或弹出框。这些是瞬时交互,不是持久的视图状态。返回页面时下拉菜单已经打开,对用户并不友好。
当 React 状态需要在隐藏时重置时,可在 useLayoutEffect 的清理函数中更新它。例如,当 Activity 隐藏组件时,这个下拉菜单会关闭:
'use client'
import { useState, useLayoutEffect } from 'react'
function SettingsDropdown() {
const [isOpen, setIsOpen] = useState(false)
// 当此组件被隐藏时关闭下拉菜单
useLayoutEffect(() => {
return () => {
setIsOpen(false)
}
}, [])
return (
<div>
<button onClick={() => setIsOpen((o) => !o)}>Options</button>
{isOpen && (
<ul>
<li>
<button>Edit Profile</button>
</li>
<li>
<button>Change Password</button>
</li>
</ul>
)}
</div>
)
}清理函数会在 Activity 隐藏组件之前重置 isOpen,因此用户返回时下拉菜单是关闭的。
你还可以使用 Link 的 onNavigate 回调,在点击导航链接时立即关闭下拉菜单。
原生弹出框#
原生弹出框将其打开状态保留在 DOM 中。在此示例中,useLayoutEffect 的清理函数调用 hidePopover() 以在 Activity 隐藏组件时关闭弹出框。
'use client'
import { useId, useLayoutEffect, useRef } from 'react'
function SettingsPopover() {
const popoverId = useId()
const popoverRef = useRef<HTMLDivElement>(null)
useLayoutEffect(() => {
const popover = popoverRef.current
return () => popover?.hidePopover()
}, [])
return (
<>
<button popoverTarget={popoverId}>Options</button>
<div id={popoverId} ref={popoverRef} popover="auto">
<button>Edit Profile</button>
<button>Change Password</button>
</div>
</>
)
}由于隐藏的页面仍留在 DOM 中,在多个页面之间复用硬编码的 ID 可能会使按钮关联到错误的弹出框。useId 为每个组件实例提供唯一的 ID,使按钮与其自身的弹出框保持关联。这同样适用于 label、aria-describedby 和 form 属性使用的 ID。
对话框和初始化逻辑#
Activity 会保留对话框的打开/关闭状态。当 Activity 再次显示该组件时,React 会重新运行其 Effect,包括初始化逻辑(例如聚焦输入框)。
何时保留: 用户正在操作的多步骤向导或设置面板。保留步骤和输入状态可避免丢失进度。
何时重置: 用户返回时应关闭的临时编辑对话框。
要在隐藏时重置打开/关闭状态,请使用下拉菜单示例中的 useLayoutEffect 清理函数。
对于通过 portal 渲染的受控对话框,请在拥有它的组件中重置打开状态,如下拉菜单示例中所示。
对于使用 showModal() 打开的原生对话框,可使用指向 <dialog> 元素的 ref,并在清理期间调用 close()。这会在 Activity 隐藏组件时关闭对话框。
useLayoutEffect(() => {
const dialog = dialogRef.current
return () => dialog?.close()
}, [])通过 URL 控制对话框#
如果对话框应在访问特定 URL 时打开,可从 search 参数派生其状态。例如,当 URL 包含 ?edit=true 时,此对话框会打开:
'use client'
import { useSearchParams, useRouter } from 'next/navigation'
import { Suspense, useEffect, useRef } from 'react'
function ProductTab() {
const router = useRouter()
return (
<>
<button onClick={() => router.push('?edit=true')}>Edit Product</button>
<Suspense fallback={null}>
<ProductDialog />
</Suspense>
</>
)
}
function ProductDialog() {
const searchParams = useSearchParams()
const router = useRouter()
const isDialogOpen = searchParams.get('edit') === 'true'
const inputRef = useRef<HTMLInputElement>(null)
useEffect(() => {
if (isDialogOpen) {
inputRef.current?.focus()
}
}, [isDialogOpen])
if (!isDialogOpen) return null
return (
<dialog open>
<input ref={inputRef} placeholder="Product name" />
<button onClick={() => router.replace('?', { scroll: false })}>
Close
</button>
</dialog>
)
}将按钮放在 <Suspense> 边界之外,可使其在对话框读取 search 参数的同时进行预渲染。如果父组件已经提供了合适的边界,请省略此示例中的边界。
通过不带 ?edit=true 的链接返回会关闭对话框。浏览器的前进和后退导航会恢复该历史记录的 URL,因此返回带 ?edit=true 的 URL 会再次打开它。
表单、输入和状态#
Activity 会跨导航保留表单输入值(文本字段、选中的选项、复选框状态)、提交结果和状态消息。
何时保留: 带筛选条件的搜索页面、用户正在撰写的草稿,或有未保存更改的设置表单。保留输入状态是最大的 UX 优势之一,因为用户不会丢失工作成果。
何时重置: "新建事务"流程(每次访问都应全新开始),或在新上下文中陈旧的成功/错误消息会造成混淆的表单。
提交时重置表单状态#
假设有一个用户创建新条目的页面。提交后,router.push 导航到新记录。由于 Activity 会保留该页面,返回时表单中仍显示之前的名称。请在事件处理器中重置状态,以保持表单为最新状态:
'use client'
import { useState } from 'react'
import { useRouter } from 'next/navigation'
export default function NewItemPage() {
const [name, setName] = useState('')
const router = useRouter()
async function handleSubmit(e: React.SubmitEvent<HTMLFormElement>) {
e.preventDefault()
const item = await createItem({ name })
setName('')
router.push(`/items/${item.id}`)
}
return (
<form onSubmit={handleSubmit}>
<input value={name} onChange={(e) => setName(e.target.value)} />
<button type="submit">Create</button>
</form>
)
}重置陈旧的状态消息#
如果提交后将状态设置到 state 中以渲染反馈消息,通常没有可靠的用户发起的事件来清除它。
用户可能通过你无法控制的 next/link 元素导航,或通过浏览器控件导航。
返回表单时会显示陈旧的消息。在这种情况下,你可以使用 useLayoutEffect 清理函数来重置表单和状态:
'use client'
import { useState, useRef, useLayoutEffect } from 'react'
function ContactForm() {
const [name, setName] = useState('')
const [status, setStatus] = useState<'idle' | 'success'>('idle')
const shouldReset = useRef(false)
async function handleSubmit(e: React.SubmitEvent<HTMLFormElement>) {
e.preventDefault()
await sendMessage({ name })
setStatus('success')
shouldReset.current = true
}
// 当 Activity 隐藏此组件时重置陈旧的成功消息
useLayoutEffect(() => {
return () => {
if (shouldReset.current) {
shouldReset.current = false
setStatus('idle')
setName('')
}
}
}, [])
return (
<form onSubmit={handleSubmit}>
<input value={name} onChange={(e) => setName(e.target.value)} />
<button type="submit">Send</button>
{status === 'success' && <p>Message sent!</p>}
</form>
)
}shouldReset ref 确保清理函数仅在成功提交后运行。如果用户在草稿中途未提交就离开,其输入会被保留。
如果你使用 useActionState,同样的方法也适用。有关如何向 reducer 添加 RESET action,请参阅 React 文档中的重置状态。有关使用这些 hook 构建响应式交互的更多信息,请参阅构建交互式应用指南。
<details> <summary>使用回调 ref 重置非受控表单字段</summary>
对于非受控输入,回调 ref 可以在 Activity 隐藏组件时调用 form.reset()。这会将输入恢复到其默认值:
'use client'
function resetOnHide(form: HTMLFormElement | null) {
return () => form?.reset()
}
function ContactForm() {
return (
<form ref={resetOnHide}>
<input name="email" />
<input name="message" />
<button type="submit">Send</button>
</form>
)
}当回调发生变化时,React 会运行之前的 ref 回调的清理函数。在组件外部定义 resetOnHide 可使其保持稳定,因此重新渲染不会意外重置表单。
form.reset() 不会重置 React 状态。对于受控输入,请像上面的示例一样重置传递给 value 或 checked 的状态。
</details>
状态和身份验证#
Activity 会跨导航保留本地组件状态(useState、DOM 输入值),包括身份验证变化。这是标准的 React 行为:props 变化(例如接收到新用户)会触发重新渲染,但不会重置现有状态。一个用户撰写的草稿不应被另一个用户看到。
对于退出登录流程,使用 window.location.href 而不是 router.push 会触发整页重新加载,从而清除所有客户端状态。
要在用户变化时无需整页重新加载就重置表单,请以用户 ID 作为 key。React 会为每个身份创建新表单,包括登录或退出登录时。
'use client'
import { useState } from 'react'
function UserScopedForm({ userId }: { userId: string | null }) {
return <DraftForm key={userId} />
}
function DraftForm() {
const [draft, setDraft] = useState('')
return <textarea value={draft} onChange={(e) => setDraft(e.target.value)} />
}全局样式#
当来源组件被 Activity 隐藏时,页面级样式(CSS 变量、z-index、全局 class)可能会影响可见页面。你可能希望在隐藏时禁用它们:隐藏页面的强调色或 z-index 覆盖不应泄漏到可见页面中。
使用回调 ref 来切换样式表的 media 属性:
<style
ref={(style) => {
if (style) style.media = '' // 可见时启用
return () => {
if (style) style.media = 'not all' // 隐藏时禁用
}
}}
>
{`:root { --page-accent: blue; }`}
</style>或者在管理多个样式元素或更复杂的清理时使用 useLayoutEffect:
'use client'
import { useLayoutEffect, useRef } from 'react'
function PageWithStyles() {
const styleRef = useRef<HTMLStyleElement>(null)
useLayoutEffect(() => {
if (styleRef.current) styleRef.current.media = ''
return () => {
if (styleRef.current) styleRef.current.media = 'not all'
}
}, [])
return <style ref={styleRef}>{`:root { --page-accent: blue; }`}</style>
}当 Activity 隐藏组件时,清理函数会设置 media="not all",从而禁用样式表。当再次可见时,Effect 会重新运行并重置 media 以启用它。
:has 选择器#
:root:has(...) 规则根据其选择器应用样式。被选中的元素和匹配的元素都不知道这种关系。这是有效的 CSS,但它绕过了 React 的数据流,并将不相关的组件耦合在一起。
对于全局状态,优先使用由 React 拥有的 data-* 属性:
<html data-modal-open={modalOpen ? "true" : undefined}>html[data-modal-open='true'] {
overflow: hidden;
}将 :has() 保留用于组件内部的局部父子样式:
.card:has(img) {
padding-top: 0;
}这不仅仅是 React 数据流或 Next.js 的问题。宽泛的 :has() 选择器是真正的性能瓶颈。请参阅 MDN 上的性能注意事项。
小知识: 如果隐藏的组件本身定义了全局
:has规则,则上一节中的切换操作会连同组件的其他样式一起禁用它。
测试#
隐藏的 Activity 内容具有 display: none,但仍留在文档中。这既适用于由 Cache Components 保留的路由,也适用于你用 <Activity> 直接隐藏的内容。它会影响使用 Playwright、Cypress 或 Puppeteer 等工具的端到端测试:
- DOM 查询可以找到隐藏元素。 选择器可能会匹配元素,而不考虑其可见性。
- 与隐藏元素的交互会失败或超时。 大多数工具在交互前会等待元素变为可见,但等待不会缩小同时匹配可见和隐藏元素的查询范围。Playwright 会将此报告为严格模式冲突。
- 断言可能匹配隐藏内容。 在断言元素存在时,请明确指定可见性。
使用考虑可见性的选择器#
优先使用查询无障碍树(会排除隐藏元素)的定位器,或在操作前按可见性过滤匹配项。在 Playwright 中,getByRole 查询默认排除隐藏元素:
// 好 - getByRole 默认排除隐藏元素
await page.getByRole('button', { name: 'Submit' }).click()
await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com')其他定位器(包括 getByLabel、getByPlaceholder 和 .locator())可能会匹配隐藏元素。请显式按可见性过滤它们:
// 显式按可见性过滤
await page
.getByLabel('Email')
.filter({ visible: true })
.fill('test@example.com')
await page.getByPlaceholder('Search...').filter({ visible: true }).fill('query')
await page.locator('.product-card').filter({ visible: true }).first().click()
await page
.locator('[data-testid="timer"]')
.filter({ visible: true })
.textContent()
// 避免 - 可能会匹配 Activity 边界中的隐藏元素
await page.getByLabel('Email').fill('test@example.com')
await page.locator('.product-card').first().click()getByRole 对 Activity、标签页导航、手风琴以及任何其他将隐藏内容保留在 DOM 中的模式都很稳健。它查询无障碍树,而后者会排除隐藏元素。哪些定位器会匹配隐藏元素因测试工具及其版本而异,因此请查阅你所用工具的文档中关于其定位器和测试辅助函数的内容以进行确认。
在组件中使用 Activity#
Cache Components 会在路由级别自动使用 Activity,但你也可以在自己的组件中直接使用 <Activity>。这对于标签页、可展开面板或任何你希望隐藏内容而不卸载它的 UI 都很有用。
预渲染隐藏内容#
Activity 可以预渲染用户尚未看到的内容。隐藏的边界以较低的优先级渲染。结合 Suspense,这使你可以为用户可能接下来查看的内容预取数据。
Server Component 可以立即开始获取数据并将 promise 传递给 Client Component。Client Component 使用 Activity 隐藏内容直到用户请求它,并在渲染时使用 use() 解析 promise:
import { Suspense } from 'react'
import { ExpandableComments } from './expandable-comments'
async function getCommentsData() {
return db.comments.findMany()
}
export default function Page() {
const commentsPromise = getCommentsData()
return (
<article>
<h1>Post Title</h1>
<p>Main content visible immediately...</p>
<ExpandableComments commentsPromise={commentsPromise} />
</article>
)
}'use client'
import { Activity, Suspense, useState, use } from 'react'
type Comment = { id: string; text: string; author: string }
export function ExpandableComments({
commentsPromise,
}: {
commentsPromise: Promise<Comment[]>
}) {
const [expanded, setExpanded] = useState(false)
return (
<>
<button onClick={() => setExpanded((e) => !e)}>
{expanded ? 'Hide Comments' : 'Show Comments'}
</button>
<Activity mode={expanded ? 'visible' : 'hidden'}>
<Suspense fallback={<CommentsSkeleton />}>
<Comments commentsPromise={commentsPromise} />
</Suspense>
</Activity>
</>
)
}
function Comments({
commentsPromise,
}: {
commentsPromise: Promise<Comment[]>
}) {
const comments = use(commentsPromise)
return (
<ul>
{comments.map((c) => (
<li key={c.id}>{c.text}</li>
))}
</ul>
)
}
function CommentsSkeleton() {
return <div>Loading comments...</div>
}Server Component 立即开始获取评论并将 promise 传递给 ExpandableComments。Activity 以较低优先级渲染隐藏内容。当用户点击"Show Comments"时,如果数据已就绪,评论会立即出现。否则,Suspense 会显示 CommentsSkeleton 直到请求完成。
Effect 和媒体清理#
当 Activity 隐藏内容时,React 会像卸载时一样运行 Effect 清理函数。这意味着如果你有适当的清理,计时器、订阅和媒体播放会自动暂停:
'use client'
import { useEffect, useState } from 'react'
function LiveTimer() {
const [count, setCount] = useState(0)
useEffect(() => {
const id = setInterval(() => setCount((c) => c + 1), 1000)
return () => clearInterval(id) // 隐藏时暂停
}, [])
return <p>Count: {count}</p>
}对于 <video> 和 <audio> 等媒体元素,display: none 不会停止播放。请使用 useLayoutEffect 添加显式的清理:
'use client'
import { useLayoutEffect, useRef } from 'react'
function VideoPlayer({ src }: { src: string }) {
const videoRef = useRef<HTMLVideoElement>(null)
useLayoutEffect(() => {
const video = videoRef.current
return () => {
video?.pause() // 隐藏时暂停,保留播放位置
}
}, [])
return <video ref={videoRef} src={src} controls />
}当组件再次变为可见时,Effect 会重新运行,并且由于 DOM 节点从未被移除,播放位置会被保留。
如果清理操作移除或更改了 DOM 属性,请在 Effect 的 setup 中恢复它。例如,以下 Effect 在隐藏时释放视频的媒体资源,并在显示时恢复其来源。它替代了上面 VideoPlayer 中的 Effect。
useLayoutEffect(() => {
const video = videoRef.current
if (!video) return
video.src = src
return () => {
video.pause()
video.removeAttribute('src')
video.load()
}
}, [src])释放来源也会重置播放位置。如果你只需要停止播放,请使用前面的 pause() 示例以保留播放位置。
跟踪 Effect 之前是否运行过#
Effect 会在每次从隐藏到可见的转换时运行,而不仅仅是在初次挂载时。ref 可以记录 Effect 之前是否运行过:
'use client'
import { useEffect, useRef } from 'react'
function TrackedComponent() {
const hasRunRef = useRef(false)
useEffect(() => {
if (!hasRunRef.current) {
hasRunRef.current = true
console.log('Effect ran for the first time')
} else {
console.log('Effect ran again')
}
}, [])
return <div>...</div>
}该 ref 会在隐藏/显示周期中持续存在。在开发环境中,Strict Mode 会额外运行一次 setup 和 cleanup 周期,因此 else 分支也可能在初次挂载时运行。这记录的是 Effect 之前是否运行过,而不是是否发生了导航。请确保 setup 和 cleanup 可安全地重复执行。
示例#
Activity 模式演示(源码)是一个启用了 Cache Components 的 Next.js 应用,包含三个路由。在它们之间导航即可查看状态保留的实际效果:
- 数据 —— 可排序表格和可选择列表,可跨导航保留状态,另有一个在后台预渲染的评论部分
- 表单 —— 带持久 DOM 状态(
<details>、复选框、文本输入)的筛选面板,以及一个使用useLayoutEffect清理在提交后重置的订阅表单 - 副作用 —— 离开时暂停、返回时恢复的实时计时器,以及自动暂停并保留播放位置的视频播放器