useMutation

const {
  data,
  error,
  isError,
  isIdle,
  isPending,
  isPaused,
  isSuccess,
  failureCount,
  failureReason,
  mutate,
  mutateAsync,
  reset,
  status,
  submittedAt,
  variables,
} = useMutation(
  {
    mutationFn,
    gcTime,
    meta,
    mutationKey,
    networkMode,
    onError,
    onMutate,
    onSettled,
    onSuccess,
    retry,
    retryDelay,
    scope,
    throwOnError,
  },
  queryClient,
)

mutate(variables, {
  onError,
  onSettled,
  onSuccess,
})

参数1 (选项)

mutation

mutationFn: (variables: TVariables, context: MutationFunctionContext) => Promise<TData>

• 一个执行异步任务并返回 Promise 的函数。

• variables 是一个对象，mutate 会将其传递给你的 mutationFn。

• context 是一个对象，mutate 会将其传递给你的 mutationFn。包含对 QueryClient、mutationKey 和可选 meta 对象的引用。

gcTime（可选）

gcTime: number | Infinity

• 未使用/非活动的缓存数据在内存中保留的时间（以毫秒为单位）。当突变的缓存变为未使用或非活动状态时，该缓存数据将在经过此持续时间后被垃圾回收。当指定了不同的缓存时间时，将使用最长的时间。

• 如果设置为 Infinity，将禁用垃圾回收。

• 注意：最大允许时间约为 24天，尽管可以使用 timeoutManager.setTimeoutProvider 来绕过此限制。

mutationKey（可选）

mutationKey: unknown[]

• 可以设置突变键以继承通过 queryClient.setMutationDefaults 设置的默认值。

networkMode（可选）

networkMode: 'online' | 'always' | 'offlineFirst'

• 默认值为 'online'

• 更多信息请参见 网络模式。

onMutate（可选）

onMutate: (variables: TVariables) => Promise<TOnMutateResult | void> | TOnMutateResult | void

• 此函数将在突变函数执行前触发，并接收与突变函数相同的变量。

• 用于在希望突变成功的情况下对资源进行乐观更新。

• 此函数返回的值将在突变失败时传递给 onError 和 onSettled 函数，可用于回滚乐观更新。

onSuccess（可选）

onSuccess: (data: TData, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => Promise<unknown> | unknown

• 当突变成功时，此函数将被触发，并接收突变的结果。

• 如果返回一个 Promise，它将在继续之前被等待和解析。

onError（可选）

onError: (err: TError, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => Promise<unknown> | unknown

• 如果突变遇到错误，此函数将被触发，并接收错误对象。

• 如果返回一个 Promise，它将在继续之前被等待和解析。

onSettled（可选）

onSettled: (data: TData, error: TError, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => Promise<unknown> | unknown

• 当突变成功获取或遇到错误时，此函数将被触发，并接收数据或错误。

• 如果返回一个 Promise，它将在继续之前被等待和解析。

retry（可选）

retry: boolean | number | (failureCount: number, error: TError) => boolean

• 默认值为 0。

• 如果为 false，失败的突变将不会重试。

• 如果为 true，失败的突变将无限重试。

• 如果设置为 number，例如 3，失败的突变将重试直到失败次数达到该数值。

retryDelay（可选）

retryDelay: number | (retryAttempt: number, error: TError) => number

• 此函数接收一个 retryAttempt 整数和实际的错误，并返回下次尝试前应用的延迟（以毫秒为单位）。

• 类似 attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) 的函数应用指数退避。

• 类似 attempt => attempt * 1000 的函数应用线性退避。

scope（可选）

scope: { id: string }

• 默认为唯一 ID（因此所有突变并行运行）

• 具有相同作用域 ID 的突变将按顺序串行运行。

throwOnError（可选）

throwOnError: undefined | boolean | (error: TError) => boolean

• 设置为 true 时，突变错误将在渲染阶段被抛出，并传播到最近的错误边界。

• 设置为 false 以禁用将错误抛出到错误边界的行为。

• 如果设置为函数，它将接收错误并应返回一个布尔值，指示是否在错误边界中显示错误（true）或将错误作为状态返回（false）。

meta（可选）

meta: Record<string, unknown>

如果设置，将在突变缓存条目上存储可按需使用的附加信息。它将在 mutation 可用的任何地方访问（例如 MutationCache 的 onError、onSuccess 函数）。

参数2 (QueryClient)

queryClient?: QueryClient

使用此参数来使用自定义 QueryClient。否则，将使用最近上下文中的 QueryClient。

返回值

mutate

mutate: (variables: TVariables, { onSuccess, onSettled, onError }) => void

• 你可以使用变量调用的突变函数来触发突变，并可选择附加回调选项。

• variables: TVariables

  • 可选

  • 要传递给 mutationFn 的变量对象。

• onSuccess: (data: TData, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => void

  • 可选

  • 当突变成功时，此函数将被触发，并接收突变的结果。

  • 无返回值函数，返回值将被忽略。

• onError: (err: TError, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => void

  • 可选

  • 如果突变遇到错误，此函数将被触发，并接收错误。

  • 无返回值函数，返回值将被忽略。

• onSettled: (data: TData | undefined, error: TError | null, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => void

  • 可选

  • 当突变成功获取或遇到错误时，此函数将被触发，并接收数据或错误。

  • 无返回值函数，返回值将被忽略。

• 如果你发出多个请求，onSuccess 将仅在你发出的最后一次调用后触发。

mutateAsync

mutateAsync: (variables: TVariables, { onSuccess, onSettled, onError }) => Promise<TData>

• 与 mutate 类似，但返回一个可等待的 Promise。

status

status: MutationStatus

将是以下之一：

• idle 在突变函数执行前的初始状态。

• pending 如果突变正在执行中。

• error 如果上次突变尝试导致错误。

• success 如果上次突变尝试成功。

isIdle, isPending, isSuccess, isError: 从 status 派生的布尔变量。

isPaused

isPaused: boolean

• 如果突变已被“暂停”，则为 true。

• 更多信息请参见 网络模式。

data

• data: undefined | unknown

  • 默认为 undefined。

  • 突变最后一次成功解析的数据。

• error: null | TError

  • 查询的错误对象，如果遇到错误。

• reset: () => void

  • 一个清理突变内部状态的函数（即，将突变重置为其初始状态）。

failureCount

failureCount: number

• 突变的失败次数。

• 每次突变失败时递增。

• 突变成功时重置为 0。

failureReason

failureReason: null | TError

• 突变重试的失败原因。

• 突变成功时重置为 null。

submittedAt

submittedAt: number

• 提交突变的时间戳。

• 默认为 0。

variables

variables: undefined | TVariables

• 传递给 mutationFn 的 variables 对象。

• 默认为 undefined。