Skip to main content

useMutation

const {
  data,
  error,
  isError,
  isIdle,
  isLoading,
  isPaused,
  isSuccess,
  failureCount,
  failureReason,
  mutate,
  mutateAsync,
  reset,
  status,
} = useMutation({
  mutationFn,
  cacheTime,
  mutationKey,
  networkMode,
  onError,
  onMutate,
  onSettled,
  onSuccess,
  retry,
  retryDelay,
  useErrorBoundary,
  meta,
});

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

Options(选项)​

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

    • 必须的，但仅当为定义默认突变函数时才需要
    • 它应该返回一个 Promise，该 Promise 将解析为突变的结果，并应返回一个 Promise，该 Promise 将解析为突变的结果
    • variables是一个对象将mutate传递给mutationFn

  • cacheTime: number | Infinity

    • 未使用/非活动缓存数据保留在内存中的时间(以毫秒为单位)。当突变的缓存变为未使用或不活动时，该缓存数据将在此持续时间之后被垃圾收集。当指定不同的缓存时间时，将使用最长的缓存时间。
    • 如果设置为Infinity，将禁用垃圾收集

  • mutationKey: unknown[]

    • 可选的
    • 可以将突变键设置为继承使用queryClient.setMutationDefaults设置的默认值

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

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

    • 可选的
    • 用于对资源执行乐观更新，希望突变成功
    • 在发生突变失败的情况下，这个函数返回的值将传递给 onError 和 onsettle 函数，对于回滚乐观更新非常有用。

  • onSuccess: (data: TData, variables: TVariables, context?: TContext) => Promise<unknown> | unknown

    • 可选的
    • 当突变成功时，此函数将触发，并将传递突变的结果
    • 如果返回的是一个 promise，则它将等待 promise 完成，并返回 promise 的结果

  • onError: (error: unknown, variables: TVariables, context?: TContext) => Promise<unknown> | unknown

    • 可选的
    • 当突变失败时，此函数将触发，并将传递错误和变量
    • 如果返回的是一个 promise，则它将等待 promise 完成，并返回 promise 的结果

  • onSettle: (data: TData | void, error: unknown | void, variables: TVariables, context?: TContext) => Promise<unknown> | unknown

    • 可选的
    • 当突变成功或失败时，此函数将触发，并将传递突变的结果和错误
    • 如果返回的是一个 promise，则它将等待 promise 完成，并返回 promise 的结果

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

    • 默认为 0
    • 如果是 false, 将不会重试失败的突变
    • 如果是 true, 将重试所有失败的突变
    • 如果是 number, 例如 3, 将重试失败的突变，最多重试 number 次

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

    • 此函数接收 retryAttempt 整数和实际错误，并返回下次尝试之前应用的延迟（以毫秒为单位）
    • 失败重试间隔时间，可以接收具体的时间，也可以接收函数，比如返回递增时间的函数

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

    • 默认为全局查询配置的 useErrorBoundary 值，该值为 undefined
    • 如果要在渲染阶段抛出错误并传播到最近的错误边界，请将其设置为 true
    • 如果要禁用 suspense 的默认行为，在错误边界中抛出错误，请将其设置为 false
    • 如果设置为函数，它将传递错误和查询，并应返回一个布尔值，指示是否在错误边界中显示错误（true）或将错误返回为状态（false）

  • meta: Record<string, unknown>

    • 可选的
    • 如果设置了该选项，将会在查询缓存条目上存储额外的信息，这些信息可以根据需要使用。它将在查询可用的任何地方访问，也是提供给 queryFn 的 QueryFunctionContext 的一部分

  • context?: React.Context<QueryClient | undefined>

    • 使用此选项来使用自定义的 React Query 上下文。否则将使用默认上下文 defaultContext

Returns(返回值)​

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

    • 您可以使用变量调用突变函数以触发突变，并可选择覆盖传递给useMutation

    • variables: TVariables

      • 可选的
      • 传递给 mutationFn 的 variables 对象

    • 其余的选项扩展了上述 useMutation 钩子中描述的相同选项

    • 如果您发出多个请求，onSuccess 只会在您最近一次调用之后触发

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

    • 类似于 mutate，但返回一个可以等待的承诺

  • status: string

    • 将会:

      • idle 突变函数执行前的初始状态
      • loading 如果突变当前正在执行
      • error 如果最后一次突变尝试导致错误
      • success 如果最后一次突变尝试成功

  • isIdle, isLoading, isSuccess, isError: 来自status的布尔变量

  • isPaused: boolean

    • 如果突变已经 paused 则为 true
    • 有关详细信息，请参阅网络模式

  • data: undefined | unknown

    • 默认为 undefined
    • 上次成功解析查询的数据

  • error: null | TError

    • 查询的错误对象（如果遇到错误）

  • reset: () => void

    • 清除突变内部状态的函数（即，它将突变重置为其初始状态）