MutationObserverOptions
定义于：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' |
控制当前网络连接状态下是否允许运行该修改。参见 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 |
在修改函数运行前调用此函数，并接收相同的变量。适用于应用乐观更新，以期修改成功。它返回的值将作为 onMutateResult 传给 onSuccess、onError 和 onSettled，通常在此处回滚乐观更新。若返回 Promise，则会在修改函数运行前等待其完成。 |
onSettled? |
(data: TData | undefined, error: TError | null, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => unknown |
undefined |
当修改成功或出错时调用此函数，并传入数据或错误。若返回 Promise，则会在修改最终确定（settle）前等待其完成。 |
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），修改将在触发后立即运行。 |
throwOnError? |
boolean | ((error: TError) => boolean) |
false |
是否应抛出错误，而非设置 error 属性。若设为 true，所有错误都将抛出至最近的错误边界；若设为函数，则会传入错误，并应返回一个布尔值，指示是否抛出错误（true）或将其作为状态返回（false）。 |