UseMutationOptions

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

定义于：packages/preact-query/src/types.ts:395

useMutation 所接受的选项。与 @tanstack/query-core 中的 MutationObserverOptions 相同，但不包含内部的 _defaulted 标志。

继承自

OmitKeyof<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, "_defaulted">

类型参数

TData

TData = unknown

你的修改函数所解析出的数据类型。

TError

TError = DefaultError

你的修改函数可能抛出的错误类型。

TVariables

TVariables = void

传入 mutate/mutateAsync 的变量类型。

TOnMutateResult

TOnMutateResult = unknown

onMutate 所返回的类型，将作为 onMutateResult 参数传入 onSuccess/onError/onSettled —— 适用于乐观更新回滚所需的数据。

属性

属性	类型	默认值	描述
`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` 整数和实际的 Error，并返回下次重试前应延迟的毫秒数。默认为一个应用指数退避策略的函数，上限为 30 秒。
`scope?`	`MutationScope`	`undefined`	控制此修改是与其他修改并行运行，还是等待轮到自己。共享相同 `scope.id` 的修改将按启动顺序串行运行。若未指定作用域，修改将在触发后立即运行。
`throwOnError?`	`boolean` \| ((`error`: `TError`) => `boolean`)	`false`	是否应抛出错误而非设置 `error` 属性。若设为 `true`，所有错误都将抛出至最近的错误边界。若设为函数，则该函数将接收错误并返回布尔值，指示是否应抛出错误（`true`）或将其作为状态返回（`false`）。