Mutation

定义位置：packages/query-core/src/mutation.ts:138

表示一次单独的修改尝试。一个 Mutation 保存了该修改的选项、状态（数据/错误/状态）以及当前订阅它的 MutationObserver。

实例由 MutationCache 内部创建并管理；应用代码通常通过 QueryClient 或框架专用 Hook（例如 useMutation）间接与修改交互。你可通过 mutationCache.find()/getAll() 直接访问 Mutation 实例，以检查缓存状态。

示例

1const mutationCache = queryClient.getMutationCache()2 3const mutation = mutationCache.find({ mutationKey: ['addPost'] })

继承自

• Removable

类型参数

TData

TData = unknown

TError

TError = DefaultError

TVariables

TVariables = unknown

TOnMutateResult

TOnMutateResult = unknown

构造函数

构造函数

1new Mutation<TData = unknown, TError = Error, TVariables = unknown, TOnMutateResult = unknown>(config: MutationConfig<TData, TError, TVariables, TOnMutateResult>): Mutation<TData, TError, TVariables, TOnMutateResult>;

定义位置：packages/query-core/src/mutation.ts:155

参数

config

MutationConfig<TData, TError, TVariables, TOnMutateResult>

返回值

Mutation<TData, TError, TVariables, TOnMutateResult>

覆盖

1Removable.constructor

属性

gcTime

1gcTime: number;

定义位置：packages/query-core/src/removable.ts:11

继承自

1Removable.gcTime

mutationId

1readonly mutationId: number;

定义位置：packages/query-core/src/mutation.ts:146

options

1options: MutationOptions<TData, TError, TVariables, TOnMutateResult>;

定义位置：packages/query-core/src/mutation.ts:145

state

1state: MutationState<TData, TError, TVariables, TOnMutateResult>;

定义位置：packages/query-core/src/mutation.ts:144

访问器

meta

获取签名

1get meta(): Record<string, unknown> | undefined;

定义位置：packages/query-core/src/mutation.ts:187

若存在，则为传入修改选项中的 meta 对象。

返回值

Record<string, unknown> | undefined

该修改的 meta；若未设置，则返回 undefined。

方法

continue()

1continue(): Promise<unknown>;

定义位置：packages/query-core/src/mutation.ts:260

恢复当前已暂停或从脱水后仍处于 pending 状态中还原的修改。

• 若该修改拥有活跃的重试器（例如因网络模式或基于作用域的排队机制而在尝试中途暂停），则其重试器将被恢复；
• 否则，若该修改的状态仍为 pending（例如它在某次尝试进行中时被脱水，且本实例中尚未获得重试器），则再次调用 execute 并传入最后已知的变量；
• 否则该修改已终结，此方法立即解析，不执行任何额外操作。

返回值

Promise<unknown>

一个最终解析为已恢复修改的 Promise：若修改失败则拒绝；若修改已终结则立即解析。

参见

Mutation#execute

示例

1// typically driven by reconnect handling, e.g. queryClient.resumePausedMutations()2const mutation = mutationCache.find({ mutationKey: ['addPost'] })3await mutation?.continue()

destroy()

1destroy(): void;

定义位置：packages/query-core/src/removable.ts:19

清除待处理的垃圾回收超时，使该条目不再被安排移除。子类可覆写此方法以释放其所持有的资源——Query 同时也会取消任何正在进行的拉取。

返回值

void

继承自

1Removable.destroy

execute()

1execute(variables: TVariables): Promise<TData>;

定义位置：packages/query-core/src/mutation.ts:301

通过重试器运行给定变量的修改函数，并驱动修改的状态及生命周期回调直至终结。

若在调用 execute 时该修改的状态已是 pending（即它从脱水状态中还原，且仍在进行中），则跳过 onMutate 步骤，并分发一个 continue 动作以取消暂停；否则先分发一个 pending 动作，再依次等待修改缓存的 onMutate 和该修改自身的 onMutate 选项，并将所得上下文存储下来。

随后执行修改函数（受 retry/retryDelay/networkMode 控制，并受修改缓存基于作用域的序列化约束）。成功时，先运行缓存的 onSuccess/onSettled 回调，再运行该修改自身的 onSuccess/onSettled 选项，然后分发一个 success 动作，并返回解析后的数据。失败时，对 onError/onSettled 同样采用“先缓存后选项”的顺序，但每个回调均单独捕获异常，确保抛出异常的回调不会掩盖原始错误；随后分发一个 error 动作，并重新抛出原始错误。

参数

variables

TVariables

传入 mutationFn 的变量。

返回值

Promise<TData>

一个解析为修改数据的 Promise，或以修改错误拒绝。

参见

Mutation#continue

示例

1// Called internally by `MutationObserver.mutate` and `Mutation.continue` —2// applications normally trigger mutations through those, not this method.3const data = await mutation.execute(variables)