用 Vite 搭 React 19 任务管理器：Actions 与乐观更新入门

想快速摸到 React 19 的 Actions、useActionState、useOptimistic，不必一上来就上 Next.js。技术栈博文以 React 19.2 + TypeScript + Vite 为基线，带出一个可独立运行的 TaskFlow 任务管理示例：创建、筛选、标记完成、删除，数据暂存 localStorage，之后可把数据层换成 REST。[1]

准备工作

• Node.js：Vite 文档要求约 20.19+ 或 22.12+，建议用仍在维护的 LTS（原文举例 Node.js 24 LTS）。

• 包管理器：npm / pnpm / Yarn / Bun 任选。

• 编辑器与可选扩展：VS Code 等；浏览器装 React Developer Tools。

先确认环境：

node -v
npm -v

操作步骤

1、用 Vite 创建 React + TS 项目

npm create vite@latest taskflow -- --template react-ts
cd taskflow
npm install
npm install react@latest react-dom@latest
npm install -D @types/react@latest @types/react-dom@latest
npm run dev

浏览器打开 http://localhost:5173，能看到默认页面即成功。可用 npm ls react react-dom 确认已到 19.x。为何这样：官方已弃用 Create React App；Vite 模板适合纯客户端练手，显式安装最新 React 才能稳定用到 Actions 相关 API。[1]

2、拆领域模型与数据层

在 src/domain/task.ts 定义任务类型（id、title、completed、createdAt）。在 src/services/taskApi.ts 用 localStorage 封装 list / create / toggle / remove：读写前把 JSON.parse 结果当 unknown 做运行时校验，写一点延迟模拟异步。不要在组件里直接碰存储。

为什么：组件只关心「任务列表变了」；以后换 HTTP 只改 taskApi。确认方式：在控制台调用 taskApi.create 后刷新，数据仍在。[1]

3、用表单 Action 做「创建任务」

TaskComposer 里用 useActionState 接管提交：

const [state, submitAction] = useActionState(async (_prev, formData) => {
  const title = String(formData.get('title') ?? '').trim();
  if (title.length < 2) return { status: 'error', message: '至少两个字符' };
  const task = await taskApi.create(title);
  onCreated(task);
  return { status: 'success', message: '创建成功' };
}, { status: 'idle', message: '' });

表单写 <form action={submitAction}>。提交按钮拆成表单内部子组件，调用 useFormStatus() 读 pending，禁用按钮并显示「创建中」。

做完怎么确认：输入单字符应出错误提示；合法标题提交后列表出现新任务，输入框清空，按钮短暂 pending。[1]

4、列表操作用乐观更新

在 App 用 useOptimistic(tasks, reducer)，勾选完成 / 删除时包进 startTransition：先 applyOptimisticAction，再 await taskApi.toggle/remove，成功则同步基础状态，失败则设错误文案（乐观层会回到基础状态）。适合勾选、删除普通项；支付、余额不要盲目乐观。[1]

5、筛选、延迟搜索与自测清单

用 useState 管「全部 / 待完成 / 已完成」，搜索词经 useDeferredValue 再过滤，减轻输入卡顿。跑 npm run dev 按序自测：创建三条 → 筛选 → 搜索 → 勾选 → 删除 → 刷新仍在。可选再加 Vitest + Testing Library 测表单校验（原文有完整示例）。[1]

常见问题

• 开发环境 Effect 跑两次：多半是 StrictMode 检查，生产不会双挂；保证 cleanup 可安全重复执行即可。[1]

• fetch 404 进不了 catch：HTTP 错误不会自动 reject，必须先判断 response.ok。[1]

• 列表输入错位：检查是否用了数组下标当 key，改成稳定业务 id。[1]

注意事项

• useFormStatus 必须在目标 <form> 的子组件里调用。

• useOptimistic 更新要落在 Action / startTransition 内。

• 纯客户端没有 RSC；需要 SEO / Server Components 再考虑 Next.js 等。前端环境变量不要放密钥。[1]

说明：步骤据技术栈原文（更新于 2026 年 8 月）整理，以本机 React / Vite 版本为准。

来源

[1] React 19 从入门到工程实践：核心原理、新特性与项目实战，技术栈，2026年8月26日。

#React19 #Vite #TypeScript #useActionState #useOptimistic #前端教程