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 (Options)

mutationFn: (variables: TVariables) => Promise<TData>
- 必需，仅在未定义默认 mutation 函数时需要
- 一个执行异步任务并返回 Promise 的函数。
- variables 是一个对象，它会被 mutate 传递给你的 mutationFn。
gcTime: number | Infinity
- 未使用的/不活跃的缓存数据将在内存中保留的时间（以毫秒为单位）。当一个 mutation 的缓存变得未使用或不活跃时，该缓存数据将在该持续时间后被垃圾回收。当指定不同的缓存时间时，将使用最长的时间。
- 如果设置为 Infinity，将禁用垃圾回收。
- 注意：允许的最大时间约为 24 天，尽管可以使用 timeoutManager.setTimeoutProvider 来绕过此限制。
mutationKey: unknown[]
- Optional (可选)
- 可以设置 mutation key 来继承使用 queryClient.setMutationDefaults 设置的默认值。
networkMode: 'online' | 'always' | 'offlineFirst'
- Optional (可选)
- 默认为 'online'
- 有关更多信息，请参阅网络模式。
onMutate: (variables: TVariables) => Promise<TContext | void> | TContext | void
- Optional (可选)
- 此函数将在 mutation 函数执行之前触发，并接收与 mutation 函数相同的变量。
- 有助于执行乐观更新，以期 mutation 成功。
- 从此函数返回的值将在 mutation 失败时传递给 onError 和 onSettled 函数，并可能用于回滚乐观更新。
onSuccess: (data: TData, variables: TVariables, context: TContext) => Promise<unknown> | unknown
- Optional (可选)
- mutation 成功时将触发此函数，并将传递 mutation 的结果。
- 如果返回 Promise，它将被等待并解析后继续执行。
onError: (err: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown
- Optional (可选)
- mutation 遇到错误时将触发此函数，并将传递错误。
- 如果返回 Promise，它将被等待并解析后继续执行。
onSettled: (data: TData, error: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown
- Optional (可选)
- mutation 成功获取或遇到错误时将触发此函数，并将传递数据或错误。
- 如果返回 Promise，它将被等待并解析后继续执行。
retry: boolean | number | (failureCount: number, error: TError) => boolean
- 默认为 0。
- 如果设置为 false，失败的 mutations 将不会重试。
- 如果设置为 true，失败的 mutations 将无限重试。
- 如果设置为一个数字，例如 3，失败的 mutation 将重试，直到失败的 mutation 数量达到该数字。
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 }
- Optional (可选)
- 默认为唯一 ID（以便所有 mutations 并行运行）
- 具有相同 scope ID 的 mutations 将串行运行
throwOnError: undefined | boolean | (error: TError) => boolean
- 如果希望 mutation 错误在渲染阶段抛出并传播到最近的错误边界，请将其设置为 true。
- 设置为 false 以禁用向错误边界抛出错误的行为。
- 如果设置为一个函数，它将接收错误并应返回一个布尔值，指示是显示错误（true）还是将错误作为状态返回（false）。
meta: Record<string, unknown>
- Optional (可选)
- 如果设置，则在 mutation 缓存条目上存储额外信息，可按需使用。它可以在 mutation 可用的任何地方访问（例如 onError、onSuccess 函数的 MutationCache）。

参数2 (QueryClient)

queryClient?: QueryClient
- 使用此选项可以使用自定义 QueryClient。否则，将使用最近上下文中的 QueryClient。

Returns (返回)

mutate: (variables: TVariables, { onSuccess, onSettled, onError }) => void
- 您可以调用 mutation 函数并传递变量来触发 mutation，以及可选的挂钩以获得额外的回调选项。
- variables: TVariables
  - Optional (可选)
  - 传递给 mutationFn 的变量对象。
- onSuccess: (data: TData, variables: TVariables, context: TContext) => void
  - Optional (可选)
  - mutation 成功时将触发此函数，并将传递 mutation 的结果。
  - Void 函数，返回值将被忽略
- onError: (err: TError, variables: TVariables, context: TContext | undefined) => void
  - Optional (可选)
  - mutation 遇到错误时将触发此函数，并将传递错误。
  - Void 函数，返回值将被忽略
- onSettled: (data: TData | undefined, error: TError | null, variables: TVariables, context: TContext | undefined) => void
  - Optional (可选)
  - mutation 成功获取或遇到错误时将触发此函数，并将传递数据或错误。
  - Void 函数，返回值将被忽略
- 如果您发出多个请求，onSuccess 将仅在您进行的最新调用后触发。
mutateAsync: (variables: TVariables, { onSuccess, onSettled, onError }) => Promise<TData>
- 类似于 mutate，但返回一个可以 await 的 Promise。
status: MutationStatus
- 将是
  - idle mutation 函数执行之前的初始状态。
  - pending 如果 mutation 当前正在执行。
  - error 如果上次 mutation 尝试导致错误。
  - success 如果上次 mutation 尝试成功。
isIdle, isPending, isSuccess, isError：基于 status 派生的布尔变量。
isPaused: boolean
- 如果 mutation 已暂停，则为 true
- 有关更多信息，请参阅网络模式。
data: undefined | unknown
- 默认为 undefined
- mutation 的最后一个成功解析的数据。
error: null | TError
- 如果遇到错误，则为查询的错误对象。
reset: () => void
- 一个用于清理 mutation 内部状态的函数（即，将 mutation 重置为其初始状态）。
failureCount: number
- mutation 的失败次数。
- 每次 mutation 失败时递增。
- mutation 成功时重置为 0。
failureReason: null | TError
- mutation 重试的失败原因。
- mutation 成功时重置为 null。
submittedAt: number
- mutation 提交的时间戳。
- 默认为 0。
variables: undefined | TVariables
- 传递给 mutationFn 的 variables 对象。
- 默认为 undefined。

想跳过文档吗？

想跳过文档吗？