React / 系统课时
完善交互与缓存同步
完善交互与缓存同步
本课在任务管理功能已经可用的基础上,补齐用户真正能感知的交互质量:加载时有反馈、无数据时有引导、危险操作先确认,并通过乐观更新让状态切换立即生效。最终还会建立清晰的缓存失效规则,避免列表、详情和分页数据彼此冲突。
学习目标
- 为任务列表设计加载、空状态、错误和确认交互
- 使用 TanStack Query 实现状态修改的乐观更新与失败回滚
- 区分直接更新缓存与失效重查的适用场景
设计交互状态
任务页面至少包含四类可见状态:首次加载、后台刷新、空结果和请求失败。首次加载可以显示骨架或提示;后台刷新不应清空现有列表;空状态需要区分“系统没有任务”和“当前筛选没有结果”。
删除、归档等不可轻易撤销的操作应先确认,普通状态切换则适合乐观更新。这样既避免无意义弹窗,也让高频操作保持流畅。

实现乐观更新
下面的主示例依赖 @tanstack/react-query。它假设应用入口已经通过 QueryClientProvider 注入查询客户端,并且后端提供 GET /api/tasks 与 PATCH /api/tasks/:id。
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
type TaskStatus = "TODO" | "DOING" | "DONE";
type Task = {
id: number;
title: string;
status: TaskStatus;
};
type TaskPageResult = {
items: Task[];
total: number;
};
type UpdateVariables = {
id: number;
status: TaskStatus;
};
const taskKeys = {
lists: () => ["tasks", "list"] as const,
list: (page: number) => ["tasks", "list", { page }] as const,
detail: (id: number) => ["tasks", "detail", id] as const,
};
async function getJson<T>(url: string, init?: RequestInit): Promise<T> {
const response = await fetch(url, {
headers: { "Content-Type": "application/json" },
...init,
});
if (!response.ok) throw new Error(`请求失败:${response.status}`);
return response.json() as Promise<T>;
}
export default function TaskListWithCache() {
const queryClient = useQueryClient();
const page = 1;
const queryKey = taskKeys.list(page);
const taskQuery = useQuery({
queryKey,
queryFn: () => getJson<TaskPageResult>(`/api/tasks?page=${page}`),
staleTime: 30_000,
});
const updateStatus = useMutation({
mutationFn: ({ id, status }: UpdateVariables) =>
getJson<Task>(`/api/tasks/${id}`, {
method: "PATCH",
body: JSON.stringify({ status }),
}),
onMutate: async (variables) => {
// 先停止旧请求,避免响应覆盖即将写入的乐观结果
await queryClient.cancelQueries({ queryKey });
const previous = queryClient.getQueryData<TaskPageResult>(queryKey);
queryClient.setQueryData<TaskPageResult>(queryKey, (current) => {
if (!current) return current;
return {
...current,
items: current.items.map((task) =>
task.id === variables.id
? { ...task, status: variables.status }
: task,
),
};
});
return { previous };
},
onError: (_error, _variables, context) => {
// 请求失败时恢复更新前的完整缓存快照
if (context?.previous) {
queryClient.setQueryData(queryKey, context.previous);
}
},
onSettled: async (_data, _error, variables) => {
await Promise.all([
queryClient.invalidateQueries({ queryKey: taskKeys.lists() }),
queryClient.invalidateQueries({
queryKey: taskKeys.detail(variables.id),
}),
]);
},
});
if (taskQuery.isPending) return <p>正在加载任务...</p>;
if (taskQuery.isError) return <p role="alert">任务加载失败,请重试。</p>;
if (taskQuery.data.items.length === 0) {
return <p>当前条件下没有任务,请创建任务或调整筛选条件。</p>;
}
return (
<section>
{taskQuery.isFetching && <p>正在同步最新数据...</p>}
<ul>
{taskQuery.data.items.map((task) => (
<li key={task.id}>
<span>{task.title}</span>
<select
value={task.status}
disabled={updateStatus.isPending}
onChange={(event) =>
updateStatus.mutate({
id: task.id,
status: event.target.value as TaskStatus,
})
}
>
<option value="TODO">待处理</option>
<option value="DOING">进行中</option>
<option value="DONE">已完成</option>
</select>
</li>
))}
</ul>
{updateStatus.isError && (
<p role="alert">状态更新失败,页面已恢复原值。</p>
)}
</section>
);
}预期结果:
首次进入页面时显示“正在加载任务...”。
列表存在时,后台刷新只显示“正在同步最新数据...”,不会清空旧内容。
切换状态后页面立即显示新状态;请求失败时恢复旧状态并提示错误。
请求成功或失败结束后,任务列表和对应详情缓存都会重新校验。接口地址、任务 ID 和网络耗时属于动态值,实际运行时可能不同。示例中的 staleTime 为 30 秒,表示这段时间内数据通常被视为新鲜,但手动失效仍会触发重新获取。
制定缓存失效策略
直接写缓存适合结果可预测且字段少的操作,例如只修改任务状态。失效重查适合服务端可能补充更新时间、操作人、权限结果或派生字段的场景。两者通常组合使用:先乐观写入提升速度,再失效重查保证最终一致。
查询键必须稳定且分层。["tasks"] 表示任务域,列表键包含筛选和分页条件,详情键包含任务 ID。更新一条任务后,可以精确失效该详情;若任务状态会影响多个筛选列表,则失效整个任务域更安全。
补充确认弹窗
删除任务前可以使用浏览器原生确认框完成最小实现。确认通过后再调用删除 mutation,成功时移除详情缓存并失效列表缓存。
async function confirmDelete(taskId: number): Promise<boolean> {
const accepted = window.confirm("删除后无法恢复,是否继续?");
if (!accepted) return false;
const response = await fetch(`/api/tasks/${taskId}`, { method: "DELETE" });
if (!response.ok) throw new Error(`删除失败:${response.status}`);
return true;
}预期结果:
点击删除后先出现确认提示。
选择取消时不发送请求。
选择确认且接口返回成功时,函数结果为 true。
接口失败时抛出错误,由调用方显示失败提示。生产项目可以替换为设计系统中的确认弹窗,但仍要保留相同语义:危险说明、取消入口、确认中的禁用状态,以及失败后的错误反馈。
验证异常与并发
在浏览器开发者工具中把网络切换为慢速模式,确认后台刷新时旧列表仍可见。再让更新接口返回 500,检查状态是否先变化、随后回滚,并出现错误提示。
连续快速修改同一任务可能产生并发覆盖。简单项目可以在 mutation 进行时禁用选择框;更复杂的项目应为每个任务维护独立提交状态,或让后端使用版本号进行并发控制。