修改 Mutations
与查询不同，修改通常意味着用于创建/更新/删除数据或执行服务器命令等副作用。
为此，React Query 导出了useMutation hook。
简单示例
下面是一个向服务器添加新 todo 的示例：
1function App() {2 const mutation = useMutation({3 mutationFn: (newTodo) => {4 return axios.post("/todos", newTodo);5 },6 });7 8 return (9 <div>10 {mutation.isLoading ? (11 "Adding todo..."12 ) : (13 <>14 {mutation.isError ? (15 <div>An error occurred: {mutation.error.message}</div>16 ) : null}1718 {mutation.isSuccess ? <div>Todo added!</div> : null}1920 <button21 onClick={() => {22 mutation.mutate({ id: new Date(), title: "Do Laundry" });23 }}24 >25 Create Todo26 </button>27 </>28 )}29 </div>30 );31}在任何给定时刻，修改只能处于以下状态之一：
isIdle或status === 'idle'- 修改目前处于闲置状态或处于全新/重置状态isLoading或status === 'loading'- 修改目前正在进行操作isError或status === 'error'- 修改遇到了错误isSuccess或status === 'success'- 修改是成功的，且数据可用
除了这些主要状态之外，还有更多的信息可用，具体取决于修改的状态：
error-isError时，则可以通过error属性获取错误data-isSuccess时，则可以通过data属性获取数据
在上面的示例中，你还看到可以通过使用单个变量或对象调用 mutate 函数来将变量传递给你的修改函数
即使只有变量，修改也没有那么特别，但是当与 onSuccess 回调，Query Client 的 invalidateQueries 方法和 Query Client 的 setQueryData 方法一起使用时，修改就成为了一个非常强大的工具。
重要说明：
mutate函数是一个异步函数，这意味着你不能在事件回调中直接使用它 (React16 及之前版本)。 如果你需要在onSubmit中访问事件，则需要将mutate包装在另一个函数中。 这是由于 React 事件池限制。
1// 在React16及之前的版本，这将无法正常工作2const CreateTodo = () => {3 const mutation = useMutation({4 mutationFn: (event) => {5 event.preventDefault();6 return fetch("/api", new FormData(event.target));7 },8 });9 10 return <form onSubmit={mutation.mutate}>...</form>;11};12 13// 这将正常工作14const CreateTodo = () => {15 const mutation = useMutation({16 mutationFn: (formData) => {17 return fetch("/api", formData);18 },19 });20 const onSubmit = (event) => {21 event.preventDefault();22 mutation.mutate(new FormData(event.target));23 };24 25 return <form onSubmit={onSubmit}>...</form>;26};重置修改的状态
在某些情况下，你需要清除 error 或修改请求的数据。
为此，你可以使用 reset 函数来处理：
1const CreateTodo = () => {2 const [title, setTitle] = useState("");3 const mutation = useMutation({ mutationFn: createTodo });4 5 const onCreateTodo = (e) => {6 e.preventDefault();7 mutation.mutate({ title });8 };9 10 return (11 <form onSubmit={onCreateTodo}>12 {mutation.error && (13 <h5 onClick={() => mutation.reset()}>{mutation.error}</h5>14 )}15 <input16 type="text"17 value={title}18 onChange={(e) => setTitle(e.target.value)}19 />20 <br />21 <button type="submit">Create Todo</button>22 </form>23 );24};副作用
useMutation 附带一些有帮助的选项。
允许在其生命周期的任何阶段快速而简单地产生副作用。
这些对于在乐观更新甚至是修改后使查询无效并重新获取都非常有用
1useMutation({2 mutationFn: addTodo,3 onMutate: (variables) => {4 // 修改即将发生！5 6 // （可选）返回包含回滚时使用的数据的上下文7 return { id: 1 };8 },9 onError: (error, variables, context) => {10 // 错误触发！11 console.log(`rolling back optimistic update with id ${context.id}`);12 },13 onSuccess: (data, variables, context) => {14 // Boom baby!15 },16 onSettled: (data, error, variables, context) => {17 // 错误或成功……这并不重要18 },19});当在任何回调函数中返回 promise 时，它将首先被等待，然后再调用下一个回调函数：
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 上定义的回调。
这可用于触发组件特定的副作用。
为此，可以在修改变量产生之后向修改函数提供任何被定义的回调选项。
支持的选项包括: onSuccess, onError 和 onSettled。
(请记住，如果组件在修改完成之前被卸载，则这些额外的回调不会被运行)
1useMutation({2 mutationFn: addTodo,3 onSuccess: (data, variables, context) => {4 // I will fire first5 },6 onError: (error, variables, context) => {7 // I will fire first8 },9 onSettled: (data, error, variables, context) => {10 // I will fire first11 },12});13 14mutate(todo, {15 onSuccess: (data, variables, context) => {16 // I will fire second!17 },18 onError: (error, variables, context) => {19 // I will fire second!20 },21 onSettled: (data, error, variables, context) => {22 // I will fire second!23 },24});持续修改
当持续修改时，onSuccess, onError and onSettled 这几个回调会有一些细微的差别。
当组件是挂载状态，且将它们传递给 mutate 函数时，它们只会被 触发一次。
这是因为在每次调用 mutate 函数时，相关的观察者都会被先移除再重新监听。
与之相反，useMutation 的处理函数会在每一次的 mutate 调用时被调用。
请注意，传递给
useMutation的mutationFn是同步的。在这种情况下，mutationFn的触发顺序和调用mutate时的顺序是有所不同的。
1useMutation({2 mutationFn: addTodo,3 onSuccess: (data, error, variables, context) => {4 // 将被调用3次5 },6});7 8[("Todo 1", "Todo 2", "Todo 3")].forEach((todo) => {9 mutate(todo, {10 onSuccess: (data, error, variables, context) => {11 // 只会被TODO3触发，而被调用一次12 // 无论之前被resolve的有多少13 },14 });15});Promises
使用 mutateAsync 而不是 mutate 来返回一个 Promise，它将在成功时解析或抛出一个错误。
例如，这可以用来组合副作用。
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}重试
默认情况下，React Query 不会在出错时重试修改，但可以使用 retry 选项：
1const mutation = useMutation({2 mutationFn: addTodo,3 retry: 3,4});如果由于设备离线而导致修改失败，那么当设备重新连接时，它们将以相同的顺序重试。
持久化
现在可以将修改持久化到数据库或其他什么存储方式中，并在以后恢复。这可以通过以下高阶函数实现：
1const queryClient = new QueryClient();2 3// 定义 "addTodo" 修改4queryClient.setMutationDefaults(["addTodo"], {5 mutationFn: addTodo,6 onMutate: async (variables) => {7 // 取消 todos list 当前的查询8 await queryClient.cancelQueries(["todos"]);9 10 // 创建一个对于 todo 的乐观修改11 const optimisticTodo = { id: uuid(), title: variables.title };12 13 // 添加到 todos list14 queryClient.setQueryData(["todos"], (old) => [...old, optimisticTodo]);15 16 // 返回包含乐观修改的上下文17 return { optimisticTodo };18 },19 onSuccess: (result, variables, context) => {20 // 成功，用正确内容替换掉21 queryClient.setQueryData(["todos"], (old) =>22 old.map((todo) => (todo.id === context.optimisticTodo.id ? result : todo))23 );24 },25 onError: (error, variables, context) => {26 // 清除掉添加失败的 todo27 queryClient.setQueryData(["todos"], (old) =>28 old.filter((todo) => todo.id !== context.optimisticTodo.id)29 );30 },31 retry: 3,32});33 34// 在同一个组件内启动修改35const mutation = useMutation({ mutationKey: ["addTodo"] });36mutation.mutate({ title: "title" });37 38// 如果因为设备离线而暂停了修改，39// 然后，当程序退出时，可以使暂停的修改变为 dehydrated 的40const state = dehydrate(queryClient);41 42// 当程序启动时，修改再次启动43hydrate(queryClient, state);44 45// 重启修改46queryClient.resumePausedMutations();持久化的离线修改
如果你使用 persistQueryClient 插件持久化一个离线的修改，除非提供一个默认修改函数，否则在页面重新加载时，修改没法恢复。
这是一个技术限制。
当持久化到外部存储时，只有修改的状态被持久化，因为函数不能被序列化。
（SSR 中）hydration 后，触发修改的组件可能没有被正确挂载，所以调用resumePausedMutations可能会产生一个错误：No mutationFn found。
1const persister = createSyncStoragePersister({2 storage: window.localStorage,3});4const queryClient = new QueryClient({5 defaultOptions: {6 queries: {7 cacheTime: 1000 * 60 * 60 * 24, // 24 hours8 },9 },10});11 12// 我们需要一个默认的修改函数，以便暂停的修改可以在页面重新加载后继续进行13queryClient.setMutationDefaults(["todos"], {14 mutationFn: ({ id, data }) => {15 return api.updateTodo(id, data);16 },17});18 19export default function App() {20 return (21 <PersistQueryClientProvider22 client={queryClient}23 persistOptions={{ persister }}24 onSuccess={() => {25 // 在从localStorage初始化恢复(initial restore from localStorage)成功后恢复修改26 queryClient.resumePausedMutations();27 }}28 >29 <RestOfTheApp />30 </PersistQueryClientProvider>31 );32}这里还有一个覆盖面更泛化的离线修改+查询的例子(codesandbox)
衍生阅读
要了解更多关于修改的信息，请查看此社区内容(英文)