构建交互式应用
了解如何使用 Server Functions、transition、乐观 UI 和 pending 反馈构建响应迅速的交互。
当一次用户交互需要服务端工作时,结果无法立即获得。网络请求需要的时间长短不定,可能成功也可能失败。在等待期间,客户端应提供反馈并响应这些状态。否则,用户只能看着过时的数据,不知道是否发生了什么。
本指南为一个名为 Taskboard 的任务管理应用添加响应式反馈。每一步处理不同类型的 pending 工作,从流式渲染缓慢的读取操作,到在服务端响应前确认变更操作。
小知识: 本指南中的模式还能改善 Core Web Vitals。使用
<Suspense>进行流式渲染,可以在缓慢的读取操作完成时先绘制外壳,从而降低 FCP 和 LCP。乐观 UI 和 transition 通过保持点击帧的快速响应来降低 INP。预取下一个路由可让目标页面的 FCP、LCP 和 INP 近乎瞬时。这些模式有所帮助,但不能替代常规的 INP 优化工作:减少客户端 JavaScript 的交付量,并避免交互期间出现阻塞性的往返请求。
示例#
这些模式按顺序逐步构建:在加载边界后流式渲染缓慢的数据、添加即时的优先级切换、使用回调 prop 构建可复用的筛选器、在评论被确认前先显示它们、在拖放时于各列之间移动卡片、在创建对话框中管理表单生命周期,以及向父组件传递 pending 删除的信号。最后一步缓存可复用的读取操作,使导航保持瞬时。
配套的 Taskboard 演示(源代码)让你可以在实际运行中查看本指南中的每种模式。
该应用按功能组织。任务领域的一切内容(查询、Server Functions 和组件)都位于 features/task/ 下。共享的 UI 基础组件位于 components/ui/,而 app/ 中的页面负责组合功能组件。本指南全文中的文件路径都遵循这一结构。
起点是一个 Server Component 应用,它从数据库读取任务和评论,没有 <Suspense> 边界,也没有缓存。Client Components 调用 Server Functions 来变更这些数据。每次变更后,Server Function 都会调用 refresh(),使服务端使用新数据重新渲染:
'use server'
import { refresh } from 'next/cache'
import { PRIORITY_CYCLE } from '@/lib/data'
import { getTaskById, updateTaskPriority } from '@/lib/db'
export async function cyclePriority(taskId: string) {
const task = await getTaskById(taskId)
if (!task) return null
const newPriority = PRIORITY_CYCLE[task.priority]
await updateTaskPriority(taskId, newPriority)
refresh()
return newPriority
}步骤 1:使用 Suspense 流式渲染缓慢的数据#
任务详情页会读取任务及其评论。当在页面组件顶部同时 await 这两项时,整个页面会阻塞,直到最慢的读取操作完成。
import { getTask } from '@/features/task/task-queries'
import { TaskDetail } from '@/features/task/components/task-detail'
import { CommentSection } from '@/features/task/components/comment-section'
export default async function TaskPage({ params }) {
const { id } = await params
const task = await getTask(id)
return (
<div>
<TaskDetail task={task} />
<CommentSection taskId={id} />
</div>
)
}在这个版本中,在 getTask 完成之前不会渲染任何内容,而评论的读取只会在那之后才开始。
将读取操作拆分到不同的组件中,为每个组件传入一个 promise,并用 <Suspense> 将它们包裹起来。页面变为同步的,会立即返回外壳,服务端则在各部分数据就绪时逐一流式渲染:
import { Suspense } from 'react'
import {
TaskDetail,
TaskDetailSkeleton,
} from '@/features/task/components/task-detail'
import {
CommentSection,
CommentSectionSkeleton,
} from '@/features/task/components/comment-section'
export default function TaskPage({ params }) {
return (
<div>
<Suspense fallback={<TaskDetailSkeleton />}>
{params.then(({ id }) => (
<>
<TaskDetail id={id} />
<Suspense fallback={<CommentSectionSkeleton />}>
<CommentSection taskId={id} />
</Suspense>
</>
))}
</Suspense>
</div>
)
}每个区块组件各自 await 自己的数据:
export async function TaskDetail({ id }) {
const task = await getTask(id)
return <TaskHeader task={task} />
}在 JSX 中内联调用 params.then() 使页面保持同步。外层的 <Suspense> 覆盖了 params 的解析和任务详情的读取。一旦 TaskDetail 完成,React 就会显示任务头部和嵌套的 <Suspense> 边界,后者会在评论加载期间显示 CommentSectionSkeleton。
现在页面外壳会立即绘制,getTask 完成时任务头部会流式渲染进来,getComments 完成时评论区紧随其后。
有关流式渲染模式的更多信息,请参阅流式渲染指南。
步骤 2:即时响应切换操作#
每张任务卡片都有一个优先级指示器,点击时会在低、中、高之间循环切换。
该按钮渲染来自服务端的 priority prop。调用 Server Function 会启动变更操作,但不会改变当前渲染中的该 prop。
这里直接调用了 Server Function:
'use client'
import { cyclePriority } from '@/features/task/task-actions'
export function TaskCard({ id, priority }) {
return (
<button onClick={() => cyclePriority(id)} className={priorityDot[priority]}>
{priority}
</button>
)
}如果点击该圆点,Server Function 会运行,但按钮会继续渲染旧的 priority prop,直到下一次服务端渲染到达。
将直接调用替换为 useOptimistic 和 useTransition。useOptimistic 提供一个值来代替过时的 prop 进行渲染,useTransition 则将 Server Function 作为 transition 的一部分运行。只要该 transition 处于 pending 状态,乐观值就会生效:
'use client'
import { useOptimistic, useTransition } from 'react'
import { cyclePriority } from '@/features/task/task-actions'
import { PRIORITY_CYCLE } from '@/lib/data'
export function TaskCard({ id, priority }) {
const [optimisticPriority, setOptimisticPriority] = useOptimistic(priority)
const [, startTransition] = useTransition()
function handlePriority() {
startTransition(async () => {
setOptimisticPriority(PRIORITY_CYCLE[optimisticPriority])
await cyclePriority(id)
})
}
return (
<button
onClick={handlePriority}
className={priorityDot[optimisticPriority]}
>
{optimisticPriority}
</button>
)
}setOptimisticPriority 调用会在当前帧用循环中的下一个值更新 UI。从 optimisticPriority 而非 prop 读取,意味着快速双击也能正确循环,而不会读取到过时的闭包值。
当 transition 结束且新数据到达时,乐观值会回退到新的服务端渲染 prop。如果 useTransition 内的 Server Function 抛出异常,错误会被转发到最近的错误边界,无需手动编写 try/catch。
现在颜色会在鼠标抬起的瞬间改变。再次点击会循环到下一个值,无需等待第一次变更完成。
步骤 3:带 pending 反馈的筛选#
看板带有标签筛选按钮(Design、Frontend、Backend)。点击某个按钮会更新查询参数以筛选任务列表。
选中的筛选条件来自 URL。调用 router.push() 会启动客户端导航,服务端会用新的 search params 重新渲染看板。在该导航完成之前,页面会继续渲染旧的 URL 状态。
这里直接调用了 router.push():
'use client'
import { useRouter, useSearchParams } from 'next/navigation'
export function LabelFilter() {
const router = useRouter()
const searchParams = useSearchParams()
function handleFilter(value: string | null) {
const params = new URLSearchParams(searchParams.toString())
if (value) params.set('label', value)
else params.delete('label')
router.push(`/?${params.toString()}`)
}
// ...使用 onClick={handleFilter} 渲染筛选按钮
}在这个版本中,router.push() 会启动导航,但没有本地的 pending 状态。按钮继续渲染旧的 URL 值,看板也没有任何迹象表明新的服务端渲染正在加载。
将筛选器拆分为两个组件。LabelFilter 负责查询字符串的更新,并将导航回调传递给可复用的 ChipGroup,由后者处理所有 pending 反馈:
'use client'
import { useRouter, useSearchParams } from 'next/navigation'
import { ChipGroup } from '@/components/ui/chip-group'
const labels = [
{ label: 'Design', value: 'design' },
{ label: 'Frontend', value: 'frontend' },
{ label: 'Backend', value: 'backend' },
]
export function LabelFilter() {
const router = useRouter()
const searchParams = useSearchParams()
const current = searchParams.get('label') ?? null
function filterAction(value: string | null) {
const params = new URLSearchParams(searchParams.toString())
if (value) {
params.set('label', value)
} else {
params.delete('label')
}
router.push(`/?${params.toString()}`)
}
return (
<ChipGroup items={labels} value={current} changeAction={filterAction} />
)
}LabelFilter 决定应用导航到哪里,自身不持有任何 pending 状态。
在内部处理 pending 反馈#
ChipGroup 接受一个 changeAction prop,并在自己的 startTransition 中调用它。它使用了两个 useOptimistic hook:一个用于选中的按钮,另一个用于 data-pending 属性,祖先组件可以基于该属性设置样式:
'use client'
import { startTransition, useOptimistic } from 'react'
export function ChipGroup({ items, value, changeAction }) {
const [optimisticValue, setOptimisticValue] = useOptimistic(value)
const [isPending, setIsPending] = useOptimistic(false)
function handleClick(newValue) {
startTransition(async () => {
setOptimisticValue(newValue)
setIsPending(true)
await changeAction(newValue)
})
}
return (
<div className="flex gap-1.5" data-pending={isPending ? '' : undefined}>
{items.map((item) => (
<button
key={item.value}
onClick={() =>
handleClick(item.value === optimisticValue ? null : item.value)
}
className={item.value === optimisticValue ? 'active' : ''}
>
{item.label}
</button>
))}
</div>
)
}使用者传入一个回调(changeAction),设计组件在 transition 中运行它。按照惯例,名为 action 或以 Action 结尾的 prop 表示这种行为。有关此模式,请参阅 React 文档中的从组件暴露 action prop。
ChipGroup 根元素上的 data-pending 属性让祖先组件无需任何协调即可通过 CSS 做出响应。首页的看板使用 group-has-data-pending:opacity-50 在 transition 运行期间变暗,而不是用骨架屏替换看板。由于 ChipGroup 渲染在 group 元素内部,该属性对任何祖先组件都可用于设置样式。
小知识:
group-has-data-pending:和has-data-pending:会编译为 CSS 的:has()选择器,每当data-pending切换时,浏览器都会对锚定子树重新求值。在这里开销很小,因为看板每次筛选只切换两次,而拖动(步骤 5)特意跳过了它。当宽泛的:has()锚点在拖动或滚动等高频交互中切换时,应改用客户端状态,因为对大型子树反复重新计算会累积开销。
"Frontend" 按钮现在会在当前帧高亮。看板在筛选数据加载期间变暗,随后更新为筛选后的任务。
步骤 4:添加带即时反馈的评论#
任务详情页有一个评论区。提交评论会在服务端写入新数据,但持久化列表由 Server Component 渲染,因此在下一次服务端渲染到达之前,它无法包含新评论。
这里的评论表单使用受控状态管理输入框,并直接调用 Server Function:
'use client'
import { useState } from 'react'
import { addComment } from '@/features/task/task-actions'
export function CommentForm({ taskId }) {
const [content, setContent] = useState('')
async function handleSubmit() {
if (!content.trim()) return
await addComment(taskId, content)
setContent('')
}
return (
<div>
<input
value={content}
onChange={(e) => setContent(e.target.value)}
placeholder="Write a comment..."
/>
<button onClick={handleSubmit}>Send</button>
</div>
)
}在这个版本中,提交时 Server Function 会运行,但输入框保持有内容,列表在服务端响应前不会变化。
将评论列表拆分为两部分。一个 Server Component 渲染持久化的评论,一个 Client Component 仅用 useOptimistic([])(初始为空数组)跟踪 pending 评论。当 transition 完成且带有新数据的新渲染到达时,pending 列表重置为空,真正的评论出现在服务端渲染的列表中:
'use client'
import { useOptimistic, useRef } from 'react'
import { addComment } from '@/features/task/task-actions'
import { CommentCard } from './comment-card'
export function OptimisticComments({ taskId }) {
const [pendingComments, setPendingComments] = useOptimistic([])
const formRef = useRef(null)
return (
<>
<form
ref={formRef}
action={async (formData) => {
const content = formData.get('content')?.trim()
if (!content) return
formRef.current?.reset()
const id = crypto.randomUUID()
setPendingComments((current) => [
{
id,
content,
userName: 'You',
createdAt: new Date().toISOString(),
},
...current,
])
await addComment(taskId, content)
}}
>
<input name="content" placeholder="Write a comment..." required />
<button type="submit">Send</button>
</form>
{pendingComments.map((comment) => (
<CommentCard key={comment.id} comment={comment} pending />
))}
</>
)
}提交时会发生三件事:
formRef.current?.reset()通过直接操作 DOM 清空输入框。在 transition 中,useState的 setter 会延迟到 transition 完成后执行,但useOptimistic的 setter 和formRef.reset()这类直接 DOM 调用会在当前帧生效。setPendingComments使用客户端生成的 UUID 将新评论添加到 pending 列表。- 表单的
action在 transition 中运行该处理函数。
Server Component 会在旁边渲染真实的列表:
import { getComments } from '@/features/task/task-queries'
import { CommentCard } from './comment-card'
import { OptimisticComments } from './optimistic-comments'
async function CommentSection({ taskId }) {
const comments = await getComments(taskId)
return (
<div>
<OptimisticComments taskId={taskId} />
{comments.map((comment) => (
<CommentCard key={comment.id} comment={comment} />
))}
</div>
)
}现在提交时输入框会清空,列表顶部会出现一张淡化的评论卡片。当服务端确认后,淡化的卡片消失,真正的评论出现在服务端渲染的列表中。
步骤 5:在各列之间移动卡片#
看板有三列:Todo、In Progress 和 Done。每一列根据服务端提供的 tasks prop 渲染任务。
放下卡片会启动一个写入新状态的 Server Function。在下次服务端渲染到达之前,tasks prop 不会变化,因此客户端需要一个临时任务列表来表示这次 pending 的移动。
这里在放下卡片时调用了 Server Function:
'use client'
import { use } from 'react'
import { updateStatus } from '@/features/task/task-actions'
export function Board({ tasksPromise }) {
const tasks = use(tasksPromise)
function handleDrop(targetStatus, taskId) {
updateStatus(taskId, targetStatus)
}
// ...根据 tasks 渲染各列
}该组件从父级 Server Component(见步骤 1 的 <Suspense> 边界)接收一个 promise,并用 use 解包。在这个版本中,从 "Todo" 拖到 "In Progress" 的卡片在服务端处理更新期间仍停留在旧列,等响应到达后才跳到新列。
添加带 reducer 的 useOptimistic,在当前帧重新映射卡片的状态。reducer 接收完整的任务列表和一个描述哪张卡片移动到何处的 action:
'use client'
import { startTransition, use, useOptimistic } from 'react'
import { toast } from 'sonner'
import { updateStatus } from '@/features/task/task-actions'
export function Board({ tasksPromise }) {
const tasks = use(tasksPromise)
const [optimisticTasks, moveTask] = useOptimistic(
tasks,
(currentTasks, action: { taskId: string; status: Status }) =>
currentTasks.map((t) =>
t.id === action.taskId ? { ...t, status: action.status } : t
)
)
function handleDrop(targetStatus, taskId) {
startTransition(async () => {
moveTask({ taskId, status: targetStatus })
const result = await updateStatus(taskId, targetStatus)
if (!result.success) toast.error(result.error)
})
}
return (
<div className="grid grid-cols-3 gap-4">
{columns.map((col) => (
<Column
key={col.status}
tasks={optimisticTasks.filter((t) => t.status === col.status)}
onDrop={(taskId) => handleDrop(col.status, taskId)}
/>
))}
</div>
)
}reducer 遍历任务列表并更新被拖动卡片的状态,其余保持不变。如果在拖动过程中有后台刷新到达(例如来自轮询或其他用户的变更),React 会用更新后的基础数据重新运行 reducer,使乐观移动叠加在新数据之上。当任务不再存在时,Server Function 会返回错误结果,客户端用 toast 显示该错误。
这一步使用独立的 startTransition 而非 useTransition,因为该 hook 的 isPending 会触发步骤 3 中的看板变暗效果。乐观移动已经提供了视觉反馈,因此不需要 pending 指示器。如果 Server Function 返回预期的错误,卡片会回退。非预期错误会被转发到最近的错误边界。
现在从 "Todo" 拖到 "In Progress" 的卡片在松手的瞬间就会落到目标列。
步骤 6:管理表单生命周期#
看板有一个 "New Task" 按钮,用于打开创建对话框。表单 action 在服务端创建任务,然后刷新看板。
在该 action 处于 pending 状态时,对话框协调三部分客户端状态:提交按钮、字段值以及对话框是否打开。useActionState 负责处理这三者。
这里的表单手动管理提交状态,并在 onSubmit 处理函数中调用 Server Function:
'use client'
import { useState } from 'react'
import { createTask } from '@/features/task/task-actions'
export function CreateTaskModal() {
const [isOpen, setIsOpen] = useState(false)
const [isSubmitting, setIsSubmitting] = useState(false)
async function handleSubmit(e) {
e.preventDefault()
const formData = new FormData(e.currentTarget)
const title = formData.get('title')
if (!title.trim()) return
setIsSubmitting(true)
await createTask({ title /* ... */ })
setIsSubmitting(false)
setIsOpen(false)
}
return (
<Dialog open={isOpen} onOpenChange={setIsOpen}>
<form onSubmit={handleSubmit}>
<input name="title" placeholder="Task title..." required />
<button type="submit" disabled={isSubmitting}>
{isSubmitting ? 'Creating...' : 'Create Task'}
</button>
</form>
</Dialog>
)
}在这个版本中,提交处理函数会运行,但由两个独立的 useState 调用管理 pending 状态。对话框会在看板显示新任务之前关闭,因为 setIsOpen(false) 在 transition 之外触发。表单字段在多次提交之间也会保留其值,除非你自己跟踪一个重置 key。
useActionState 处理这三方面:isPending 用于按钮,基于 key 的重置用于字段,以及包裹对话框的关闭操作:
'use client'
import { useActionState, startTransition, useState } from 'react'
import { createTask } from '@/features/task/task-actions'
export function CreateTaskModal() {
const [isOpen, setIsOpen] = useState(false)
const [{ key }, formAction, isPending] = useActionState(
async (prev, formData) => {
const title = String(formData.get('title'))
if (!title.trim()) return prev
await createTask({
title,
description: String(formData.get('description')),
status: 'todo',
priority: 'medium',
})
startTransition(() => setIsOpen(false))
return { key: prev.key + 1 }
},
{ key: 0 }
)
return (
<Dialog open={isOpen} onOpenChange={setIsOpen}>
<form action={formAction}>
<div key={key}>
<input name="title" placeholder="Task title..." required />
<input name="description" placeholder="Describe the task..." />
</div>
<button type="submit" disabled={isPending}>
{isPending ? 'Creating...' : 'Create Task'}
</button>
</form>
</Dialog>
)
}返回状态中的 key 控制表单重置。成功后 key 递增,从而重新挂载 <div key={key}> 并重置其中的每个输入框。
useActionState 将 action 作为 transition 运行,因此在 createTask 运行期间对话框保持打开,isPending 保持为 true。await 之后的状态更新不会自动成为该 transition 的一部分,因此将 setIsOpen(false) 包裹在 startTransition 中,可让关闭操作作为 transition 的一部分运行。
有了这层包裹,React 会将对话框的关闭与 createTask 内部 refresh() 触发的看板更新一起批处理,因此新任务会在对话框关闭的瞬间出现。没有它的话,对话框会先关闭,看板则晚一帧更新。
小知识: React 文档中以 React 不会将我在
await之后的状态更新视为 transition 记录了这一限制。在修复之前,推荐将await之后的状态更新包裹在startTransition中作为变通方案。
同样,await 之后的这个窗口也适合放置 toast 等副作用:
await createTask({
/* … */
})
startTransition(() => setIsOpen(false))
toast.success('Task created')不影响渲染状态的副作用(如分析、toast 和焦点变更)应在 await 完成后运行。它们不需要 transition,因为不会更新 React 状态。
现在按钮文本会在提交时变为 "Creating..." 并变暗。当服务端响应后,字段清空、对话框关闭、新任务出现在看板上,并有 toast 确认该操作。
小知识: 配套应用在对话框中添加了状态、优先级、负责人和标签选择器。模式相同:隐藏输入框跟踪每个选择器的状态,
key在成功时将它们全部重置。
步骤 7:向父组件传递 pending 删除信号#
每张评论卡片都有一个删除按钮,可在服务端删除评论,评论在下一次渲染后从列表中消失。
在点击与该次渲染之间,卡片仍显示旧数据。列表本身无法显示 pending 的删除,因此信号必须来自按钮。
这一步复用了步骤 3 中的 data-pending CSS 钩子,但由 useOptimistic(false) 驱动,而非 useTransition 的 isPending。
这里直接调用了 Server Function:
'use client'
import { Trash2 } from 'lucide-react'
import { deleteComment } from '@/features/task/task-actions'
export function DeleteButton({ commentId }) {
return (
<button
onClick={() => deleteComment(commentId)}
aria-label="Delete comment"
>
<Trash2 className="size-3" />
</button>
)
}在这个版本中,评论在下一次服务端渲染之前保持完全可见。
将该 action 包裹在 <form> 中,用 useOptimistic(false) 跟踪 pending 状态,并通过 data-pending 属性暴露出来。将 action 作为 deleteAction prop 接收,以便父级评论卡片通过 CSS 做出响应:
'use client'
import { useOptimistic } from 'react'
import { Trash2 } from 'lucide-react'
export function DeleteButton({
deleteAction,
}: {
deleteAction: () => void | Promise<void>
}) {
const [isPending, setIsPending] = useOptimistic(false)
return (
<form
action={async () => {
setIsPending(true)
await deleteAction()
}}
>
<button
type="submit"
disabled={isPending}
data-pending={isPending ? '' : undefined}
aria-label="Delete comment"
>
<Trash2 className="size-3" />
</button>
</form>
)
}父级评论卡片使用 Tailwind 的 has-data-pending: 变体,在任意后代设置 data-pending 属性时让自身淡出。按钮是唯一知道删除何时处于 pending 状态的组件,因此将该状态暴露为 CSS 属性,可让任何祖先组件自行变暗,而无需提升状态或层层传递回调:
<div className="rounded-lg px-3 transition-all has-data-pending:opacity-30">
{deleteAction && <DeleteButton deleteAction={deleteAction} />}
</div>父级 Server Component 将 Server Function 绑定到评论 ID,从而保持 DeleteButton 的可复用性:
<CommentCard
comment={comment}
deleteAction={
comment.userName === 'You'
? deleteComment.bind(null, comment.id)
: undefined
}
/>现在卡片在点击被注册的瞬间淡出到 30% 不透明度。当服务端确认且下一次渲染到达时,卡片从列表中卸载。
步骤 8:让重复导航瞬时完成#
到目前为止,每种模式都只是让单次交互更流畅。跨导航时,相同的读取会重新执行,相同的 fallback 会再次绘制。对可复用的读取进行缓存,并用真实请求预取它们,可以弥补这一不足,而无需将数据模型搬进浏览器。
这一步使用 Next.js 16 引入的 Cache Components。步骤 1 至 7 在不使用它的情况下也能工作。如果你没有使用 Cache Components,请参阅不使用 Cache Components 的缓存。
在 next.config.ts 中启用它:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig启用 Cache Components 会对所有路由应用预渲染验证,而不仅是本步骤涉及的路由。在 <Suspense> 之外读取 cookies()、headers() 或 searchParams 等请求数据的路由现在会阻止预渲染,需要按步骤 1 的方式处理。要在现有应用中启用它,请参阅迁移到 Cache Components。
缓存可复用的读取#
对每一次服务端读取,都要考虑它是否应跨请求复用,以及每次写入能否精确地使其失效。任务足够稳定,适合缓存,并且有清晰的按 id 划分的标签:
import { cacheLife, cacheTag } from 'next/cache'
import { getTaskById } from '@/lib/db'
export async function getTask(id: string) {
'use cache'
cacheLife('hours')
cacheTag('tasks', `task-${id}`)
return getTaskById(id)
}按 id 划分的标签 task-${id} 让单个任务拥有自己的句柄。更宽泛的 tasks 标签涵盖列表。有关缓存范围('use cache: private'、'use cache: remote')、缓存生命周期和标签模式,请参阅缓存指南。
通过变更操作使缓存失效#
refresh() 会重新运行动态工作,但保留缓存条目。对于每次写入涉及的标签,请用 updateTag 替换它:
'use server'
import { updateTag } from 'next/cache'
import { updateTaskStatus } from '@/lib/db'
export async function updateStatus(taskId: string, newStatus: Status) {
const updated = await updateTaskStatus(taskId, newStatus)
if (!updated) {
return { success: false as const, error: 'Task no longer exists' }
}
updateTag('tasks')
updateTag(`task-${taskId}`)
return { success: true as const, status: newStatus }
}每个 Server Function 都遵循相同的模式:执行写入,然后为发生变化的缓存读取调用 updateTag。动态读取没有需要失效的标签,因此这些变更操作应使用 refresh()。
在本演示中,评论串保持动态,因为读者期望当前讨论能在打开的任务页面上立即更新。添加或删除评论会调用 refresh(),为当前路由重新运行动态评论读取,同时保留任务缓存。有关标签模式、基于时间的重新验证以及从 Route Handler 进行按需失效,请参阅重新验证指南。
用真实请求预取目标页面#
在 Partial Prefetching(Next.js 16.3 及更高版本)下,<Link> 会预取目标页面的 App Shell:即针对当前用户在多个链接之间共享的路由输出。该外壳不包含 URL data,因为 params 和 searchParams 是与具体链接相关的。通过 prefetch={true} 让链接选择逐链接预取,即可在点击前解析这些 URL data:
<Link href={`/task/${id}`} prefetch={true}>
</Link>当目标页面包含用户接下来很可能需要、且与具体 URL 相关的工作时,逐链接预取最有价值。缓存的读取让预取输出在 Client Cache 中可复用且可按标签失效;动态读取仍可在点击前解析,但每次预取都可能执行真正的服务端工作。在配套应用中,任务卡片会在滚动进入视口时预取详情页,因此用户点击时页面已能瞬时绘制。
后续步骤#
本指南中的模式组合了少量基础能力:
| 场景 | 使用 |
|---|---|
| 缓慢的数据应在不阻塞页面的情况下流式渲染 | <Suspense> |
| 某个值应在异步工作运行期间更新 | useOptimistic |
| 异步工作需要 pending 状态、错误处理或协调的 UI 更新 | useTransition |
| 表单需要 pending、重置和结果状态 | useActionState |
| 祖先组件应为别处发生的工作显示 pending 状态 | data-pending 属性,配合 CSS 设置样式 |
| 可复用的读取应跨请求保留,并在写入后保持新鲜 | 'use cache' 配合 cacheTag,由 updateTag 或 revalidateTag 重新验证 |
| 交互式应用中页面间的导航应感觉瞬时 | <Link> 预取结合 Partial Prefetching,以及通过 prefetch={true} 对依赖 URL data 的内容使用逐链接预取 |
大多数模式会混合使用其中两种或更多。选择适合你所要解决的约束的基础能力即可。
相关指南: