译零 TransZero · TanStack Query 中文文档

主站

MutationObserverOptions

更新于 2026-11-02 Solid 查看英文原文 ↗

定义于：packages/query-core/src/types.ts:1992

一个 MutationObserver 及其上构建的 Hook（例如 useMutation）所用的选项：即 MutationOptions 加上 throwOnError。

继承自

MutationOptions<TData, TError, TVariables, TOnMutateResult>

类型参数

TData

TData = unknown

TError

TError = DefaultError

TVariables

TVariables = void

TOnMutateResult

TOnMutateResult = unknown

属性

属性	类型	默认值	描述
`gcTime?`	`number`	`undefined`	未使用/非活跃修改在内存中保留的毫秒数，超过该时间后将被垃圾回收。默认为 `5 * 60 * 1000`（5 分钟），服务端渲染（SSR）期间为 `Infinity`。
`meta?`	`Record`<`string`, `unknown`>	`undefined`	存储在修改缓存项上的额外负载。可用于传递可在任何存在 `mutation` 的位置读取的信息，例如 `MutationCache` 的 `onError` 和 `onSuccess` 回调函数。
`mutationFn?`	(`variables`: `TVariables`, `context`: `MutationFunctionContext`) => `Promise`<`TData`>	`undefined`	执行此修改所对应异步任务的函数。必需，除非已通过 `queryClient.setMutationDefaults` 为匹配的 `mutationKey` 设置了默认修改函数。接收传入 `mutate` 的 `variables`，以及一个包含 `QueryClient`、`mutationKey` 和 `meta` 的 MutationFunctionContext。必须返回一个解析出修改数据的 Promise。
`mutationKey?`	readonly `unknown`[]	`undefined`	此修改所用的修改键。可选，但若要继承通过 `queryClient.setMutationDefaults` 注册的默认值，或与 `useMutationState` 或 `queryClient.isMutating` 匹配，则必须提供。
`networkMode?`	`"online"` \| `"always"` \| `"offlineFirst"`	`'online'`	控制修改是否允许基于当前网络连接状态运行。参见网络模式获取更多信息。
`onError?`	(`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: `MutationFunctionContext`) => `unknown`	`undefined`	当修改遇到错误时触发此函数，并传入该错误。若返回 Promise，则会在 `onSettled` 运行前等待其完成。
`onMutate?`	(`variables`: `TVariables`, `context`: `MutationFunctionContext`) => `TOnMutateResult` \| `Promise`<`TOnMutateResult`>	`undefined`	此函数在修改函数运行前触发，并接收相同的变量。适用于在期望修改成功前提下应用的乐观更新。其返回值将作为 `onMutateResult` 传给 `onSuccess`、`onError` 和 `onSettled`，通常在此处回滚乐观更新。若返回 Promise，则会在修改函数运行前等待其完成。
`onSettled?`	(`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: `MutationFunctionContext`) => `unknown`	`undefined`	此函数在修改成功或失败时均会触发，并传入数据或错误。若返回 Promise，则会在修改最终确定前等待其完成。
`onSuccess?`	(`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: `MutationFunctionContext`) => `unknown`	`undefined`	此函数在修改成功时触发，并传入修改结果。若返回 Promise，则会在 `onSettled` 运行前等待其完成。
`retry?`	\| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`)	`0`	若设为 `false`，失败的修改默认不重试；若设为 `true`，失败的修改将无限重试；若设为整数（例如 3），则失败的修改将重试直至失败次数达到该数值；若设为函数 `(failureCount, error) => boolean`，则失败的修改将重试直至该函数返回 false。
`retryDelay?`	`number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`)	`undefined`	此函数接收一个 `retryAttempt` 整数和实际错误，并返回下次尝试前应延迟的毫秒数。默认为一个应用指数退避（上限为 30 秒）的函数。
`scope?`	`MutationScope`	`undefined`	控制此修改是与其他修改并行运行，还是等待轮到自己。共享相同 `scope.id` 的修改将按启动顺序串行运行。若未指定作用域，修改将在触发后立即运行。
`throwOnError?`	`boolean` \| ((`error`: `TError`) => `boolean`)	`false`	是否应抛出错误而非设置 `error` 属性。若设为 `true`，所有错误都将抛出至最近的错误边界；若设为函数，则会传入错误并应返回布尔值，指示是否抛出错误（`true`）或将其作为状态返回（`false`）。