본문으로 건너뛰기

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, context: MutationFunctionContext) => 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 정수와 실제 Error를 받아 다음 시도 전에 적용할 지연 시간을 밀리초 단위로 반환합니다.
    • attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)과 같은 함수는 지수 백오프를 적용합니다.
    • attempt => attempt * 1000과 같은 함수는 선형 백오프를 적용합니다.
  • scope: { id: string }
    • 선택 사항
    • 기본값은 고유한 id입니다(따라서 모든 뮤테이션이 병렬로 실행됩니다).
    • 동일한 scope id를 가진 뮤테이션은 직렬로 실행됩니다.
  • throwOnError: undefined | boolean | (error: TError) => boolean
    • 뮤테이션 오류가 렌더링 단계에서 발생하여 가장 가까운 오류 경계로 전파되도록 하려면 이를 true로 설정합니다
    • 오류를 error boundary에 발생시키는 동작을 비활성화하려면 이를 false로 설정합니다.
    • 함수로 설정하면 오류가 함수에 전달되며, 함수는 오류 경계에 오류를 표시할지(true) 또는 오류를 상태로 반환할지(false)를 나타내는 boolean을 반환해야 합니다.
  • meta: Record<string, unknown>
    • 선택 사항
    • 설정하면 필요에 따라 사용할 수 있는 추가 정보를 뮤테이션 캐시 항목에 저장합니다. 이 정보는 mutation을 사용할 수 있는 모든 위치(예: MutationCache의 onError, onSuccess 함수)에서 접근할 수 있습니다.

파라미터2(QueryClient)

  • queryClient?: QueryClient
    • 사용자 지정 QueryClient를 사용하려면 이를 사용합니다. 그렇지 않으면 가장 가까운 context의 항목이 사용됩니다.

반환값

  • mutate: (variables: TVariables, { onSuccess, onSettled, onError }) => void
    • 변수와 함께 호출하여 뮤테이션을 트리거하고 선택적으로 추가 콜백 옵션에 훅을 지정할 수 있는 뮤테이션 함수입니다.
    • variables: TVariables
      • 선택 사항
      • mutationFn에 전달할 변수 객체입니다.
    • onSuccess: (data: TData, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => void
      • 선택 사항
      • 이 함수는 뮤테이션이 성공하면 실행되며 뮤테이션 결과가 전달됩니다.
      • Void 함수이며 반환된 값은 무시됩니다
    • onError: (err: TError, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => void
      • 선택 사항
      • 뮤테이션에서 오류가 발생하면 이 함수가 실행되며 오류가 전달됩니다.
      • Void 함수이며 반환된 값은 무시됩니다
    • onSettled: (data: TData | undefined, error: TError | null, variables: TVariables, onMutateResult: TOnMutateResult | undefined, context: MutationFunctionContext) => void
      • 선택 사항
      • 이 함수는 뮤테이션을 성공적으로 가져오거나 오류가 발생했을 때 실행되며 데이터 또는 오류가 전달됩니다
      • Void 함수이며 반환된 값은 무시됩니다
    • 여러 요청을 수행하면 onSuccess는 가장 최근에 호출한 요청 이후에만 실행됩니다.
  • mutateAsync: (variables: TVariables, { onSuccess, onSettled, onError }) => Promise<TData>
    • mutate와 유사하지만 await할 수 있는 Promise를 반환합니다.
  • status: MutationStatus
    • 다음과 같습니다:
      • 뮤테이션 함수가 실행되기 전의 idle 초기 상태입니다.
      • 뮤테이션이 현재 실행 중이면 pending입니다.
      • 마지막 뮤테이션 시도에서 오류가 발생했다면 error입니다.
      • 마지막 뮤테이션 시도가 성공한 경우 success입니다.
  • isIdle, isPending, isSuccess, isError: status에서 파생된 boolean 변수
  • 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입니다.