useMutation useMutation 写操作
最后更新：2026-10-28
useMutation useMutation 写操作
useMutation 管理写操作（POST/PUT/DELETE）的异步状态：mutate 触发请求，isPending/isError 反馈进度，onSuccess 失效相关查询让列表自动刷新。它不缓存数据，只管这一次提交。
| 分组 | 数据与工程化 |
|---|---|
| 类型 | Hook |
| 引入版本 | TanStack Query v5 |
ℹ️ 说明 编辑器将 JSX 转译为 JavaScript 后在沙箱中渲染真实界面；组件自动挂载，无需手写 render 调用。
📝 语法
import { useMutation, useQueryClient } from '@tanstack/react-query'
const qc = useQueryClient()
const mutation = useMutation({
mutationFn: newTodo => fetch('/api/todos', {
method: 'POST',
body: JSON.stringify(newTodo)
}).then(r => r.json()),
onSuccess: () => {
qc.invalidateQueries({ queryKey: ['todos'] }) // 列表失效 → 自动重取
}
})
mutation.mutate({ title: '新任务' }) // 触发提交⚙️ 参数
| mutationFn | 必填。执行写操作的异步函数，mutate(variables) 的变量会作为入参传入。 |
|---|---|
| onSuccess / onError | 回调钩子：成功后失效查询、失败后弹提示；也可在 mutate(v, { onSuccess }) 处按次覆盖。 |
返回值：返回 { mutate, isPending, isError, data, error }：mutate(variables) 触发请求（不返回 Promise），mutateAsync 才返回 Promise。
▶ 示例
示例可直接运行：展开后自动渲染，编辑代码即时生效。
输出结果：
点提交按钮变「保存中…」并禁用 1 秒，随后列表多一项、显示成功提示——mutate 触发 → isPending → onSuccess 的完整流程（模拟演示）。💡 要点
⚠️ 注意 mutate 不返回 Promise（结果经回调交付）；在 async 函数里需要 await 时用 mutateAsync，并自行 try/catch。
💡 提示 写成功后调 invalidateQueries 而不是手动改列表——让缓存层重取，保证服务端与本地一致。
ℹ️ 说明 乐观更新（onMutate 先改缓存、失败再回滚）也由 useMutation 的回调链完成，提交体验可做到零延迟。
🏷️ 数据与工程化相关
💡 相关案例
更多案例整理中，敬请期待。
📚 相关教程
❓ 常见问题
Q useMutation 和 useQuery 最核心的区别？
A Query 读数据且带缓存、可后台重取；Mutation 写数据、不缓存、由用户动作显式触发。读用 Query，写用 Mutation 是基本分工。
Q 提交后列表怎么自动更新？
A onSuccess 里 queryClient.invalidateQueries({ queryKey: ['todos'] }) 把列表查询标记失效，useQuery 自动重取最新数据。
Q 防止按钮重复提交怎么做？
A 用 isPending 禁用按钮（如示例），或提交前判断状态；服务端仍需幂等设计兜底。
