MutationOptions
定义于：packages/query-core/src/types.ts:1880
修改（mutation）的选项：其 mutationFn、mutationKey、回调函数、重试策略、scope 等。
继承自
类型参数
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 |
此修改所用的查询键（mutation key）。可选，但若要继承通过 queryClient.setMutationDefaults 注册的默认配置，或与 useMutationState 或 queryClient.isMutating 匹配，则必须提供。 |
networkMode? |
"online" | "always" | "offlineFirst" |
'online' |
控制修改是否允许基于当前网络连接状态运行。参见 Network Mode 获取更多信息。 |
onError? |
(error: TError, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => unknown |
undefined |
当修改发生错误时调用此函数，并传入错误对象。若返回 Promise，则会在 onSettled 运行前等待其完成。 |
onMutate? |
(variables: TVariables, context: MutationFunctionContext) => TOnMutateResult | Promise<TOnMutateResult> |
undefined |
在修改函数执行前调用此函数，并接收相同的变量。适用于乐观更新（optimistic update），即在期望修改成功前提前应用更新。其返回值将作为 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，并返回下次重试前应延迟的毫秒数。默认实现为指数退避（exponential backoff），上限为 30 秒。 |
scope? |
MutationScope |
undefined |
控制此修改是与其他修改并行运行，还是等待轮到自己。共享相同 scope.id 的修改将按启动顺序串行执行。若未指定作用域（scope），修改将在触发后立即运行。 |