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

Parameter1 (Options)

mutationFn: (variables: TVariables) => Promise<TData>
- Erforderlich, aber nur, wenn keine Standard-Mutationsfunktion definiert wurde.
- Eine Funktion, die eine asynchrone Aufgabe ausführt und ein Promise zurückgibt.
- Die variables sind ein Objekt, das mutate an Ihre mutationFn übergibt.
gcTime: number | Infinity
- Die Zeit in Millisekunden, die ungenutzte/inaktive Cache-Daten im Speicher verbleiben. Wenn ein Mutations-Cache ungenutzt oder inaktiv wird, werden diese Cache-Daten nach dieser Dauer vom Garbage Collector bereinigt. Wenn unterschiedliche Cache-Zeiten angegeben sind, wird die längste verwendet.
- Wenn auf Infinity gesetzt, wird die automatische Speicherbereinigung deaktiviert.
- Hinweis: Die maximal zulässige Zeit beträgt etwa 24 Tage, es ist jedoch möglich, diese Grenze mit timeoutManager.setTimeoutProvider zu umgehen.
mutationKey: unknown[]
- Optional
- Ein Mutationsschlüssel kann gesetzt werden, um Standardwerte zu erben, die mit queryClient.setMutationDefaults definiert wurden.
networkMode: 'online' | 'always' | 'offlineFirst'
- Optional
- standardmäßig 'online'
- weitere Informationen finden Sie unter Netzwerkmodus.
onMutate: (variables: TVariables) => Promise<TContext | void> | TContext | void
- Optional
- Diese Funktion wird aufgerufen, bevor die Mutationsfunktion ausgeführt wird, und erhält dieselben Variablen, die die Mutationsfunktion erhalten würde.
- Nützlich, um optimistische Updates für eine Ressource durchzuführen, in der Hoffnung, dass die Mutation erfolgreich ist.
- Der von dieser Funktion zurückgegebene Wert wird sowohl an die onError- als auch an die onSettled-Funktionen im Falle eines Mutationsfehlers übergeben und kann nützlich sein, um optimistische Updates rückgängig zu machen.
onSuccess: (data: TData, variables: TVariables, context: TContext) => Promise<unknown> | unknown
- Optional
- Diese Funktion wird aufgerufen, wenn die Mutation erfolgreich ist, und erhält das Ergebnis der Mutation.
- Wenn ein Promise zurückgegeben wird, wird es erwartet und aufgelöst, bevor fortgefahren wird.
onError: (err: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown
- Optional
- Diese Funktion wird aufgerufen, wenn die Mutation einen Fehler aufweist, und erhält den Fehler.
- Wenn ein Promise zurückgegeben wird, wird es erwartet und aufgelöst, bevor fortgefahren wird.
onSettled: (data: TData, error: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown
- Optional
- Diese Funktion wird aufgerufen, wenn die Mutation entweder erfolgreich abgerufen wurde oder einen Fehler aufweist, und erhält entweder die Daten oder den Fehler.
- Wenn ein Promise zurückgegeben wird, wird es erwartet und aufgelöst, bevor fortgefahren wird.
retry: boolean | number | (failureCount: number, error: TError) => boolean
- Standardmäßig 0.
- Wenn false, werden fehlgeschlagene Mutationen nicht wiederholt.
- Wenn true, werden fehlgeschlagene Mutationen unendlich wiederholt.
- Wenn auf eine Zahl gesetzt, z. B. 3, werden fehlgeschlagene Mutationen wiederholt, bis die Anzahl der fehlgeschlagenen Mutationen diesen Wert erreicht.
retryDelay: number | (retryAttempt: number, error: TError) => number
- Diese Funktion empfängt eine Ganzzahl retryAttempt und den tatsächlichen Fehler und gibt die Verzögerung in Millisekunden zurück, die vor dem nächsten Versuch angewendet werden soll.
- Eine Funktion wie attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) wendet exponentielle Rückkopplung an.
- Eine Funktion wie attempt => attempt * 1000 wendet lineare Rückkopplung an.
scope: { id: string }
- Optional
- Standardmäßig eine eindeutige ID (damit alle Mutationen parallel ausgeführt werden).
- Mutationen mit derselben Scope-ID werden seriell ausgeführt.
throwOnError: undefined | boolean | (error: TError) => boolean
- Setzen Sie dies auf true, wenn Mutationsfehler in der Renderphase ausgelöst und an das nächstgelegene Fehlerboundary weitergegeben werden sollen.
- Setzen Sie dies auf false, um das Auslösen von Fehlern an das Fehlerboundary zu deaktivieren.
- Wenn auf eine Funktion gesetzt, wird diese mit dem Fehler aufgerufen und sollte einen booleschen Wert zurückgeben, der angibt, ob der Fehler in einem Fehlerboundary angezeigt werden soll (true) oder der Fehler als Status zurückgegeben werden soll (false).
meta: Record<string, unknown>
- Optional
- Wenn gesetzt, werden zusätzliche Informationen im Mutations-Cache-Eintrag gespeichert, die nach Bedarf verwendet werden können. Sie sind dort zugänglich, wo die mutation verfügbar ist (z. B. in den onError, onSuccess Funktionen des MutationCache).

Parameter2 (QueryClient)

queryClient?: QueryClient
- Verwenden Sie dies, um einen benutzerdefinierten QueryClient zu verwenden. Andernfalls wird der aus dem nächsten Kontext verwendet.

Gibt zurück

mutate: (variables: TVariables, { onSuccess, onSettled, onError }) => void
- Die Mutationsfunktion, die Sie mit Variablen aufrufen können, um die Mutation auszulösen, und optional Hooks für zusätzliche Callback-Optionen.
- variables: TVariables
  - Optional
  - Das Variablenobjekt, das an die mutationFn übergeben wird.
- onSuccess: (data: TData, variables: TVariables, context: TContext) => void
  - Optional
  - Diese Funktion wird aufgerufen, wenn die Mutation erfolgreich ist, und erhält das Ergebnis der Mutation.
  - Void-Funktion, der Rückgabewert wird ignoriert.
- onError: (err: TError, variables: TVariables, context: TContext | undefined) => void
  - Optional
  - Diese Funktion wird aufgerufen, wenn die Mutation einen Fehler aufweist, und erhält den Fehler.
  - Void-Funktion, der Rückgabewert wird ignoriert.
- onSettled: (data: TData | undefined, error: TError | null, variables: TVariables, context: TContext | undefined) => void
  - Optional
  - Diese Funktion wird aufgerufen, wenn die Mutation entweder erfolgreich abgerufen wurde oder einen Fehler aufweist, und erhält entweder die Daten oder den Fehler.
  - Void-Funktion, der Rückgabewert wird ignoriert.
- Wenn Sie mehrere Anfragen stellen, wird onSuccess erst nach dem letzten von Ihnen getätigten Aufruf ausgelöst.
mutateAsync: (variables: TVariables, { onSuccess, onSettled, onError }) => Promise<TData>
- Ähnlich wie mutate, gibt aber ein Promise zurück, das erwartet werden kann.
status: MutationStatus
- Wird
  - idle anfänglicher Status vor der Ausführung der Mutationsfunktion.
  - pending wenn die Mutation gerade ausgeführt wird.
  - error wenn der letzte Mutationsversuch zu einem Fehler geführt hat.
  - success wenn der letzte Mutationsversuch erfolgreich war.
isIdle, isPending, isSuccess, isError: boolesche Variablen abgeleitet von status
isPaused: boolean
- wird true sein, wenn die Mutation pausiert wurde.
- weitere Informationen finden Sie unter Netzwerkmodus.
data: undefined | unknown
- Standardmäßig undefined
- Die zuletzt erfolgreich aufgelösten Daten für die Mutation.
error: null | TError
- Das Fehlerobjekt für die Abfrage, falls ein Fehler aufgetreten ist.
reset: () => void
- Eine Funktion zum Bereinigen des internen Mutationszustands (d. h. sie setzt die Mutation auf ihren ursprünglichen Zustand zurück).
failureCount: number
- Die Fehleranzahl für die Mutation.
- Wird jedes Mal inkrementiert, wenn die Mutation fehlschlägt.
- Auf 0 zurückgesetzt, wenn die Mutation erfolgreich ist.
failureReason: null | TError
- Der Fehlergrund für den Wiederholungsversuch der Mutation.
- Auf null zurückgesetzt, wenn die Mutation erfolgreich ist.
submittedAt: number
- Der Zeitstempel für die Einreichung der Mutation.
- Standardmäßig 0.
variables: undefined | TVariables
- Das variables-Objekt, das an die mutationFn übergeben wurde.
- Standardmäßig undefined.

Möchten Sie die Dokumentation überspringen?

Möchten Sie die Dokumentation überspringen?