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 (选项)

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

  • 必需，但前提是未定义默认突变函数

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

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

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

• gcTime: number | Infinity

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

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

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

• mutationKey: unknown[]

  • 可选

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

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

  • 可选

  • 默认值为 'online'

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

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

  • 可选

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

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

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

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

  • 可选

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

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

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

  • 可选

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

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

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

  • 可选

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

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

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

  • 默认值为 0。

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

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

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

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

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

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

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

• scope: { id: string }

  • 可选

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

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

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

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

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

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

• meta: Record<string, unknown>

  • 可选

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

参数2 (QueryClient)

• queryClient?: QueryClient

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

返回值

• 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: (variables: TVariables, { onSuccess, onSettled, onError }) => Promise<TData>

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

• status: MutationStatus

  • 将是以下之一：

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

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

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

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

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

• isPaused: boolean

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

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

• data: undefined | unknown

  • 默认为 undefined。

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

• error: null | TError

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

• reset: () => void

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

• failureCount: number

  • 突变的失败次数。

  • 每次突变失败时递增。

  • 突变成功时重置为 0。

• failureReason: null | TError

  • 突变重试的失败原因。

  • 突变成功时重置为 null。

• submittedAt: number

  • 提交突变的时间戳。

  • 默认为 0。

• variables: undefined | TVariables

  • 传递给 mutationFn 的 variables 对象。

  • 默认为 undefined。