修改
与查询不同，修改通常用于创建/更新/删除数据或执行服务端副作用。为此，TanStack Query 导出了一个 createMutation 函数。
以下是一个向服务器添加新待办事项的修改示例：
1<script lang="ts">2 const mutation = createMutation(() => ({3 mutationFn: (newTodo) => {4 return axios.post('/todos', newTodo)5 },6 }))7</script>8 9<div>10 {#if mutation.isPending}11 <span>Adding todo...</span>12 {:else if mutation.isError}13 <div>An error occurred: {mutation.error.message}</div>14 {:else if mutation.isSuccess}15 <div>Todo added!</div>16 {/if}17 <button18 onclick={() => {19 mutation.mutate({ id: new Date(), title: 'Do Laundry' })20 }}21 >22 Create Todo23 </button>24</div>在任意时刻，一个修改只能处于以下状态之一：
isIdle或status === 'idle'—— 修改当前处于空闲或新鲜/重置状态isPending或status === 'pending'—— 修改正在运行中isError或status === 'error'—— 修改遇到了错误isSuccess或status === 'success'—— 修改成功完成，且修改数据可用
除上述主要状态外，还可根据修改所处状态获取更多信息：
error—— 若修改处于error状态，则可通过error属性获取错误信息。data—— 若修改处于success状态，则可通过data属性获取数据。
在上面的示例中，你还看到可以通过向 mutate 函数传入单个变量或对象，将变量传递给你的修改函数。
即使仅使用变量，修改本身也并不特别；但当配合 onSuccess 选项、Query Client 的 invalidateQueries 方法 和 Query Client 的 setQueryData 方法 使用时，修改便成为一种非常强大的工具。
重置修改状态
有时你需要清除某个修改请求的 error 或 data。为此，可使用 reset 函数来处理：
1<script lang="ts">2 let title = $state('')3 const mutation = createMutation(() => ({4 mutationFn: createTodo,5 }))6</script>7 8<form9 onsubmit={(e) => {10 e.preventDefault()11 mutation.mutate({ title: title })12 }}13>14 {#if mutation.error}15 <h5 onclick={() => mutation.reset()}>{mutation.error}</h5>16 {/if}17 <input18 type="text"19 value={title}20 oninput={(e) => (title = e.currentTarget.value)}21 />22 <br />23 <button type="submit">Create Todo</button>24</form>修改副作用
createMutation 提供了一些辅助选项，允许你在修改生命周期的任一阶段快速便捷地执行副作用。这些选项既适用于 修改后使查询失效并重新拉取，也适用于 乐观更新。
1createMutation(() => ({2 mutationFn: addTodo,3 onMutate: (variables, context) => {4 // A mutation is about to happen!5 6 // Optionally return a result containing data to use when for example rolling back7 return { id: 1 }8 },9 onError: (error, variables, onMutateResult, context) => {10 // An error happened!11 console.log(`rolling back optimistic update with id ${onMutateResult.id}`)12 },13 onSuccess: (data, variables, onMutateResult, context) => {14 // Boom baby!15 },16 onSettled: (data, error, variables, onMutateResult, context) => {17 // Error or success... doesn't matter!18 },19}))若在任意回调函数中返回一个 Promise，它将在调用下一个回调前被等待（await）：
1createMutation(() => ({2 mutationFn: addTodo,3 onSuccess: async () => {4 console.log("I'm first!")5 },6 onSettled: async () => {7 console.log("I'm second!")8 },9}))你可能希望在调用 mutate 时，触发超出 createMutation 上定义的回调之外的额外回调。这可用于触发组件特定的副作用。为此，你可在修改变量之后，向 mutate 函数传入任意相同的回调选项。支持的选项包括：onSuccess、onError 和 onSettled。请注意，若组件在修改完成前已卸载，则这些额外回调不会执行。
1const mutation = createMutation(() => ({2 mutationFn: addTodo,3 onSuccess: (data, variables, onMutateResult, context) => {4 // I will fire first5 },6 onError: (error, variables, onMutateResult, context) => {7 // I will fire first8 },9 onSettled: (data, error, variables, onMutateResult, context) => {10 // I will fire first11 },12}))13 14mutation.mutate(todo, {15 onSuccess: (data, variables, onMutateResult, context) => {16 // I will fire second!17 },18 onError: (error, variables, onMutateResult, context) => {19 // I will fire second!20 },21 onSettled: (data, error, variables, onMutateResult, context) => {22 // I will fire second!23 },24})连续修改
在处理连续修改时，onSuccess、onError 和 onSettled 回调的行为略有不同。当它们作为参数传给 mutate 函数时，仅在组件仍处于挂载状态时触发一次。这是因为每次调用 mutate 函数时，修改观察者都会被移除并重新订阅。相反，createMutation 的处理器会对每次 mutate 调用都执行。
请注意，传给
createMutation的mutationFn很可能是异步的。此时，修改实际完成的顺序可能与mutate函数调用的顺序不一致。
1const mutation = createMutation(() => ({2 mutationFn: addTodo,3 onSuccess: (data, variables, onMutateResult, context) => {4 // Will be called 3 times5 },6}))7 8const todos = ['Todo 1', 'Todo 2', 'Todo 3']9todos.forEach((todo) => {10 mutation.mutate(todo, {11 onSuccess: (data, variables, onMutateResult, context) => {12 // Will execute only once, for the last mutation (Todo 3),13 // regardless which mutation resolves first14 },15 })16})Promise
使用 mutateAsync 替代 mutate，可获得一个 Promise：成功时解析（resolve），出错时抛出（throw）。例如，这可用于组合副作用。
1const mutation = createMutation(() => ({ mutationFn: addTodo }))2 3try {4 const todo = { title: 'Do Laundry' }5 const todo = await mutation.mutateAsync(todo)6 console.log(todo)7} catch (error) {8 console.error(error)9} finally {10 console.log('done')11}重试
默认情况下，TanStack Query 不会在修改出错时重试，但可通过 retry 选项启用重试：
1const mutation = createMutation(() => ({2 mutationFn: addTodo,3 retry: 3,4}))若因设备离线导致修改失败，则设备重连后，这些修改将按相同顺序重试。
持久化修改
如有需要，修改可持久化到存储中，并在后续恢复执行。这可通过注水函数实现：
1const queryClient = new QueryClient()2 3// Define the "addTodo" mutation4queryClient.setMutationDefaults(['addTodo'], {5 mutationFn: addTodo,6 onMutate: async (variables, context) => {7 // Cancel current queries for the todos list8 await context.client.cancelQueries({ queryKey: ['todos'] })9 10 // Create optimistic todo11 const optimisticTodo = { id: uuid(), title: variables.title }12 13 // Add optimistic todo to todos list14 context.client.setQueryData(['todos'], (old) => [15 ...(old ?? []),16 optimisticTodo,17 ])18 19 // Return a result with the optimistic todo20 return { optimisticTodo }21 },22 onSuccess: (result, variables, onMutateResult, context) => {23 // Replace optimistic todo in the todos list with the result24 context.client.setQueryData(['todos'], (old) =>25 old.map((todo) =>26 todo.id === onMutateResult.optimisticTodo.id ? result : todo,27 ),28 )29 },30 onError: (error, variables, onMutateResult, context) => {31 // Remove optimistic todo from the todos list32 context.client.setQueryData(['todos'], (old) =>33 old.filter((todo) => todo.id !== onMutateResult.optimisticTodo.id),34 )35 },36 retry: 3,37})38 39// Start mutation in some component:40const mutation = createMutation(() => ({ mutationKey: ['addTodo'] }))41mutation.mutate({ title: 'title' })42 43// If the mutation has been paused because the device is for example offline,44// Then the paused mutation can be dehydrated when the application quits:45const state = dehydrate(queryClient)46 47// The mutation can then be hydrated again when the application is started:48hydrate(queryClient, state)49 50// Resume the paused mutations:51queryClient.resumePausedMutations()这是技术限制所致。当持久化到外部存储时，仅会持久化修改的状态，因为函数无法被序列化。注水后，触发该修改的组件可能尚未挂载，因此调用 resumePausedMutations 可能引发错误：No mutationFn found。
修改作用域
默认情况下，所有修改均并行执行——即使你多次调用同一个修改的 .mutate()。可通过为修改指定一个 scope 并配合 id 来避免这种情况。所有具有相同 scope.id 的修改将串行执行，这意味着当它们被触发时，若该作用域内已有修改正在运行，则新修改将进入 isPaused: true 状态；它们会被加入队列，并在其轮到执行时自动恢复。
1const mutation = createMutation(() => ({2 mutationFn: addTodo,3 scope: {4 id: 'todo',5 },6}))