mutationOptions

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

TypeScript

1function mutationOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(options: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>): MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>;

定义位置：packages/lit-query/src/mutationOptions.ts:20

为 Lit Query API 重用而保留并类型化修改选项。

类型参数

TData

TData = unknown

TError

TError = Error

TVariables

TVariables = void

TOnMutateResult

TOnMutateResult = unknown

参数

options

MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>

需保留的修改选项。

`options` 属性

属性	类型	默认值	描述
`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，则会在修改最终完成前等待其完成。
`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`）。

返回值