useMutation

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，它将被等待并解析，然后再继续
onError: (err: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown
- 可选
- 如果突变遇到错误，将触发此函数，并将传递该错误。
- 如果返回 Promise，它将被等待并解析，然后再继续
onSettled: (data: TData, error: TError, variables: TVariables, context?: TContext) => 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 整数和实际的 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 可用的任何位置（例如 onError、onSuccess 函数的 MutationCache）访问。

参数 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。
status: string
- 将是
  - 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。

想要跳过文档？

想要跳过文档？