修改
与查询不同，修改通常用于创建/更新/删除数据或执行服务端副作用。为此，TanStack Query 导出了一个 useMutation Hook。
以下是一个将新待办事项添加到服务端的修改示例：
1<script setup>2import { useMutation } from '@tanstack/vue-query'34const { isPending, isError, error, isSuccess, mutate } = useMutation({5 mutationFn: (newTodo) => axios.post('/todos', newTodo),6})78function addTodo() {9 mutate({ id: new Date(), title: 'Do Laundry' })10}11</script>12 13<template>14 <span v-if="isPending">Adding todo...</span>15 <span v-else-if="isError">An error occurred: {{ error.message }}</span>16 <span v-else-if="isSuccess">Todo added!</span>17 <button @click="addTodo">Create Todo</button>18</template>在任意时刻，一个修改只能处于以下状态之一：
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 setup>2import { useMutation } from '@tanstack/vue-query'34const { error, mutate, reset } = useMutation({5 mutationFn: (newTodo) => axios.post('/todos', newTodo),6})78function addTodo() {9 mutate({ id: new Date(), title: 'Do Laundry' })10}11</script>12 13<template>14 <span v-if="error">15 <span>An error occurred: {{ error.message }}</span>16 <button @click="reset">Reset error</button>17 </span>18 <button @click="addTodo">Create Todo</button>19</template>修改副作用
useMutation 提供了一些辅助选项，允许你在修改生命周期的任意阶段快速便捷地执行副作用。这些选项既适用于 修改后使查询失效并重新拉取，也适用于 乐观更新。
1useMutation({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，则该 Promise 将先被等待（await），然后才会调用下一个回调：
1useMutation({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 时，触发超出 useMutation 上定义的回调之外的额外回调。这可用于触发组件特定的副作用。为此，你可在修改变量之后，向 mutate 函数传入任意相同类型的回调选项。支持的选项包括：onSuccess、onError 和 onSettled。请注意：若你的组件在修改完成前卸载，则这些额外回调将不会执行。
1useMutation({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 14mutate(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 函数时，修改观察者都会被移除并重新订阅。相反，useMutation 上定义的处理器会在每次 mutate 调用时都执行。
请注意：传递给
useMutation的mutationFn很可能为异步函数。此时，修改实际完成的顺序可能与mutate函数调用的顺序不一致。
1useMutation({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 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 = useMutation({ mutationFn: addTodo })2 3try {4 const todo = await mutation.mutateAsync(todo)5 console.log(todo)6} catch (error) {7 console.error(error)8} finally {9 console.log('done')10}重试
默认情况下，TanStack Query 不会在修改出错时重试，但可通过 retry 选项启用重试：
1const mutation = useMutation({2 mutationFn: addTodo,3 retry: 3,4})若因设备离线导致修改失败，则当设备重新联网后，这些修改将按原有顺序重试。
持久化修改
如有需要，修改可持久化至存储并在后续恢复。这可通过注水（hydration）函数实现：
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) => [...old, optimisticTodo])15 16 // Return a result with the optimistic todo17 return { optimisticTodo }18 },19 onSuccess: (result, variables, onMutateResult, context) => {20 // Replace optimistic todo in the todos list with the result21 context.client.setQueryData(['todos'], (old) =>22 old.map((todo) =>23 todo.id === onMutateResult.optimisticTodo.id ? result : todo,24 ),25 )26 },27 onError: (error, variables, onMutateResult, context) => {28 // Remove optimistic todo from the todos list29 context.client.setQueryData(['todos'], (old) =>30 old.filter((todo) => todo.id !== onMutateResult.optimisticTodo.id),31 )32 },33 retry: 3,34})35 36// Start mutation in some component:37const mutation = useMutation({ mutationKey: ['addTodo'] })38mutation.mutate({ title: 'title' })39 40// If the mutation has been paused because the device is for example offline,41// Then the paused mutation can be dehydrated when the application quits:42const state = dehydrate(queryClient)43 44// The mutation can then be hydrated again when the application is started:45hydrate(queryClient, state)46 47// Resume the paused mutations:48queryClient.resumePausedMutations()持久化离线修改
若你使用 persistQueryClient 插件 持久化离线修改，则页面重载后无法恢复这些修改，除非你提供默认的修改函数。
这是技术限制所致：向外部存储持久化时，仅能保存修改的状态，而函数无法被序列化。注水后，触发修改的组件可能尚未挂载，因此调用 resumePausedMutations 可能报错：No mutationFn found。
1const queryClient = new QueryClient({2 defaultOptions: {3 queries: {4 gcTime: 24 * 60 * 60 * 1000, // 24 hours5 },6 },7})8 9// we need a default mutation function so that paused mutations can resume after a page reload10queryClient.setMutationDefaults(['todos'], {11 mutationFn: ({ id, data }) => {12 return api.updateTodo(id, data)13 },14})15 16const vueQueryOptions: VueQueryPluginOptions = {17 queryClient,18 clientPersister: (queryClient) => {19 return persistQueryClient({20 queryClient,21 persister: createAsyncStoragePersister({ storage: localStorage }),22 })23 },24 clientPersisterOnSuccess: (queryClient) => {25 queryClient.resumePausedMutations()26 },27}28 29createApp(App).use(VueQueryPlugin, vueQueryOptions).mount('#app')我们还提供了详尽的 离线示例，涵盖查询与修改两方面。
修改作用域
默认情况下，所有修改均并行执行——即使你多次调用同一修改的 .mutate()。可通过为修改指定 scope 并配合 id 来避免这种情况。所有具有相同 scope.id 的修改将串行执行，这意味着：当它们被触发时，若该作用域内已有修改正在进行，则新修改将进入 isPaused: true 状态；它们会被加入队列，并在其轮到执行时自动恢复。
1const mutation = useMutation({2 mutationFn: addTodo,3 scope: {4 id: 'todo',5 },6})