useMutation | TanStack Query Vue Docs

tsx

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,
})

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) => Promise<TData>
- 必需，但仅当未定义默认变更函数时
- 执行异步任务并返回 Promise 的函数。
- variables 是 mutate 将传递给您的 mutationFn 的对象
gcTime: number | Infinity
- 未使用/非活动缓存数据在内存中保留的时间（以毫秒为单位）。当变更的缓存变为未使用或非活动状态时，该缓存数据将在此持续时间后进行垃圾回收。当指定不同的缓存时间时，将使用最长的时间。
- 如果设置为 Infinity，将禁用垃圾回收
- 注意：允许的最大时间约为 24 天。请参阅更多。
mutationKey: unknown[]
- 可选
- 可以设置变更键以继承使用 queryClient.setMutationDefaults 设置的默认值。
networkMode: 'online' | 'always' | 'offlineFirst'
- 可选
- 默认为 'online'
- 有关更多信息，请参阅网络模式。
onMutate: (variables: TVariables) => Promise<TContext | void> | TContext | void
- 可选
- 此函数将在变更函数触发之前触发，并传递变更函数将接收的相同变量
- 可用于对资源执行乐观更新，以期变更成功
- 此函数返回的值将传递给 onError 和 onSettled 函数（如果变更失败），并且可用于回滚乐观更新。
onSuccess: (data: TData, variables: TVariables, context: TContext) => Promise<unknown> | unknown
- 可选
- 此函数将在变更成功时触发，并将传递变更的结果。
- 如果返回 Promise，则在继续之前将等待并解析该 Promise
onError: (err: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown
- 可选
- 如果变更遇到错误，则此函数将触发，并将传递错误。
- 如果返回 Promise，则在继续之前将等待并解析该 Promise
onSettled: (data: TData, error: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown
- 可选
- 此函数将在变更成功获取或遇到错误时触发，并将传递数据或错误
- 如果返回 Promise，则在继续之前将等待并解析该 Promise
retry: boolean | number | (failureCount: number, error: TError) => boolean
- 默认为 0。
- 如果为 false，则失败的变更默认情况下不会重试。
- 如果为 true，则失败的变更将无限次重试。
- 如果设置为数字，例如 3，则失败的变更将重试，直到失败的变更计数达到该数字。
retryDelay: number | (retryAttempt: number, error: TError) => number
- 此函数接收一个 retryAttempt 整数和实际的 Error，并返回在下一次尝试之前应用的延迟（以毫秒为单位）。
- 诸如 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, context: TContext) => void
  - 可选
  - 此函数将在变更成功时触发，并将传递变更的结果。
  - Void 函数，将忽略返回值
- onError: (err: TError, variables: TVariables, context: TContext | undefined) => void
  - 可选
  - 如果变更遇到错误，则此函数将触发，并将传递错误。
  - Void 函数，将忽略返回值
- onSettled: (data: TData | undefined, error: TError | null, variables: TVariables, context: TContext | undefined) => void
  - 可选
  - 此函数将在变更成功获取或遇到错误时触发，并将传递数据或错误
  - Void 函数，将忽略返回值
- 如果您发出多个请求，onSuccess 将仅在您发出的最新调用之后触发。
mutateAsync: (variables: TVariables, { onSuccess, onSettled, onError }) => Promise<TData>
- 与 mutate 类似，但返回一个 Promise，可以等待该 Promise。
status: string
- 将是：
  - idle 变更函数执行之前的初始状态。
  - pending 如果变更当前正在执行。
  - error 如果上次变更尝试导致错误。
  - success 如果上次变更尝试成功。
isIdle, isPending, isSuccess, isError：从上面的 status 变量派生的布尔变量
isPaused: boolean
- 如果变更已 paused，则为 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。