useQuery

tsx

const {
  data,
  dataUpdatedAt,
  error,
  errorUpdatedAt,
  failureCount,
  failureReason,
  fetchStatus,
  isError,
  isFetched,
  isFetchedAfterMount,
  isFetching,
  isInitialLoading,
  isLoading,
  isLoadingError,
  isPaused,
  isPending,
  isPlaceholderData,
  isRefetchError,
  isRefetching,
  isStale,
  isSuccess,
  isEnabled,
  promise,
  refetch,
  status,
} = useQuery(
  {
    queryKey,
    queryFn,
    gcTime,
    enabled,
    networkMode,
    initialData,
    initialDataUpdatedAt,
    meta,
    notifyOnChangeProps,
    placeholderData,
    queryKeyHashFn,
    refetchInterval,
    refetchIntervalInBackground,
    refetchOnMount,
    refetchOnReconnect,
    refetchOnWindowFocus,
    retry,
    retryOnMount,
    retryDelay,
    select,
    staleTime,
    structuralSharing,
    subscribed,
    throwOnError,
  },
  queryClient,
)

const {
  data,
  dataUpdatedAt,
  error,
  errorUpdatedAt,
  failureCount,
  failureReason,
  fetchStatus,
  isError,
  isFetched,
  isFetchedAfterMount,
  isFetching,
  isInitialLoading,
  isLoading,
  isLoadingError,
  isPaused,
  isPending,
  isPlaceholderData,
  isRefetchError,
  isRefetching,
  isStale,
  isSuccess,
  isEnabled,
  promise,
  refetch,
  status,
} = useQuery(
  {
    queryKey,
    queryFn,
    gcTime,
    enabled,
    networkMode,
    initialData,
    initialDataUpdatedAt,
    meta,
    notifyOnChangeProps,
    placeholderData,
    queryKeyHashFn,
    refetchInterval,
    refetchIntervalInBackground,
    refetchOnMount,
    refetchOnReconnect,
    refetchOnWindowFocus,
    retry,
    retryOnMount,
    retryDelay,
    select,
    staleTime,
    structuralSharing,
    subscribed,
    throwOnError,
  },
  queryClient,
)

Parameter1 (Options)

queryKey: unknown[]
- Erforderlich
- Der Abfrageschlüssel, der für diese Abfrage verwendet werden soll.
- Der Query-Schlüssel wird zu einem stabilen Hash gehasht. Weitere Informationen finden Sie unter Query Keys.
- Die Abfrage wird automatisch aktualisiert, wenn sich dieser Schlüssel ändert (solange enabled nicht auf false gesetzt ist).
queryFn: (context: QueryFunctionContext) => Promise<TData>
- Erforderlich, aber nur, wenn keine Standard-Abfragefunktion definiert wurde Weitere Informationen finden Sie unter Standard-Abfragefunktion.
- Die Funktion, die die Query zum Abrufen von Daten verwendet.
- Empfängt einen QueryFunctionContext
- Muss ein Promise zurückgeben, das entweder Daten auflöst oder einen Fehler auslöst. Die Daten dürfen nicht undefined sein.
enabled: boolean | (query: Query) => boolean
- Setzen Sie dies auf false, um zu verhindern, dass diese Abfrage automatisch ausgeführt wird.
- Kann für abhängige Abfragen verwendet werden.
networkMode: 'online' | 'always' | 'offlineFirst'
- optional
- standardmäßig 'online'
- Weitere Informationen finden Sie unter Netzwerkmodus.
retry: boolean | number | (failureCount: number, error: TError) => boolean
- Wenn false, werden fehlgeschlagene Abfragen standardmäßig nicht wiederholt.
- Wenn true, werden fehlgeschlagene Abfragen unendlich oft wiederholt.
- Wenn auf eine Zahl gesetzt, z. B. 3, werden fehlgeschlagene Abfragen wiederholt, bis die Anzahl der fehlgeschlagenen Abfragen diese Zahl erreicht.
- standardmäßig 3 auf dem Client und 0 auf dem Server
retryOnMount: boolean
- Wenn auf false gesetzt, wird die Abfrage bei einem Fehler beim Mounten nicht wiederholt. Standardmäßig true.
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.
staleTime: number | 'static' | ((query: Query) => number | 'static')
- Optional
- Standardmäßig 0
- Die Zeit in Millisekunden, nach der Daten als veraltet gelten. Dieser Wert gilt nur für den Hook, auf dem er definiert ist.
- Wenn auf Infinity gesetzt, gelten die Daten nicht als veraltet, es sei denn, sie werden manuell ungültig gemacht
- Wenn auf eine Funktion gesetzt, wird die Funktion mit der Abfrage ausgeführt, um eine staleTime zu berechnen.
- Wenn auf 'static' gesetzt, gelten die Daten niemals als veraltet
gcTime: number | Infinity
- Standardmäßig 5 * 60 * 1000 (5 Minuten) oder Infinity während SSR
- Die Zeit in Millisekunden, in der ungenutzte/inaktive Cache-Daten im Speicher verbleiben. Wenn der Cache einer Abfrage ungenutzt oder inaktiv wird, werden diese Cache-Daten nach dieser Dauer bereinigt. Wenn unterschiedliche Bereinigungszeiten angegeben werden, wird die längste verwendet.
- Hinweis: Die maximal zulässige Zeit beträgt etwa 24 Tage, es ist jedoch möglich, diese Grenze mit timeoutManager.setTimeoutProvider zu umgehen.
- Wenn auf Infinity gesetzt, wird die automatische Speicherbereinigung deaktiviert.
queryKeyHashFn: (queryKey: QueryKey) => string
- Optional
- Wenn angegeben, wird diese Funktion verwendet, um den queryKey in einen String zu hashen.
refetchInterval: number | false | ((query: Query) => number | false | undefined)
- Optional
- Wenn auf eine Zahl gesetzt, werden alle Abfragen in diesem Intervall in Millisekunden kontinuierlich erneut abgefragt.
- Wenn auf eine Funktion gesetzt, wird die Funktion mit der Abfrage ausgeführt, um ein Intervall zu berechnen.
refetchIntervalInBackground: boolean
- Optional
- Wenn auf true gesetzt, werden Abfragen, die mit einem refetchInterval kontinuierlich erneut abgefragt, auch dann weiter abgefragt, wenn ihr Tab/Fenster im Hintergrund ist.
refetchOnMount: boolean | "always" | ((query: Query) => boolean | "always")
- Optional
- Standardmäßig true
- Wenn auf true gesetzt, wird die Abfrage beim Mounten erneut abgefragt, wenn die Daten veraltet sind.
- Wenn auf false gesetzt, wird die Abfrage beim Mounten nicht erneut abgefragt.
- Wenn auf "always" gesetzt, wird die Abfrage beim Mounten immer neu abgerufen (außer wenn staleTime: 'static' verwendet wird).
- Wenn auf eine Funktion gesetzt, wird die Funktion mit der Abfrage ausgeführt, um den Wert zu berechnen.
refetchOnWindowFocus: boolean | "always" | ((query: Query) => boolean | "always")
- Optional
- Standardmäßig true
- Wenn auf true gesetzt, wird die Abfrage beim Fokus auf das Fenster erneut abgefragt, wenn die Daten veraltet sind.
- Wenn auf false gesetzt, wird die Abfrage beim Fokus auf das Fenster nicht erneut abgefragt.
- Wenn auf "always" gesetzt, wird die Abfrage bei Fokus auf das Fenster immer neu abgerufen (außer wenn staleTime: 'static' verwendet wird).
- Wenn auf eine Funktion gesetzt, wird die Funktion mit der Abfrage ausgeführt, um den Wert zu berechnen.
refetchOnReconnect: boolean | "always" | ((query: Query) => boolean | "always")
- Optional
- Standardmäßig true
- Wenn auf true gesetzt, wird die Abfrage bei Wiederherstellung der Verbindung erneut abgefragt, wenn die Daten veraltet sind.
- Wenn auf false gesetzt, wird die Abfrage bei Wiederherstellung der Verbindung nicht erneut abgefragt.
- Wenn auf "always" gesetzt, wird die Abfrage bei Wiederverbindung immer neu abgerufen (außer wenn staleTime: 'static' verwendet wird).
- Wenn auf eine Funktion gesetzt, wird die Funktion mit der Abfrage ausgeführt, um den Wert zu berechnen.
notifyOnChangeProps: string[] | "all" | (() => string[] | "all" | undefined)
- Optional
- Wenn gesetzt, wird die Komponente nur neu gerendert, wenn sich eine der aufgelisteten Eigenschaften ändert.
- Wenn beispielsweise auf ['data', 'error'] gesetzt, wird die Komponente nur neu gerendert, wenn sich die Eigenschaften data oder error ändern.
- Wenn auf "all" gesetzt, wird die Komponente vom Smart-Tracking ausgenommen und jedes Mal neu gerendert, wenn eine Abfrage aktualisiert wird.
- Wenn auf eine Funktion gesetzt, wird die Funktion ausgeführt, um die Liste der Eigenschaften zu berechnen.
- Standardmäßig wird der Zugriff auf Eigenschaften verfolgt, und die Komponente wird nur neu gerendert, wenn sich eine der verfolgten Eigenschaften ändert.
select: (data: TData) => unknown
- Optional
- Diese Option kann verwendet werden, um Daten zu transformieren oder einen Teil der von der Abfragefunktion zurückgegebenen Daten auszuwählen. Sie wirkt sich auf den zurückgegebenen data-Wert aus, hat aber keinen Einfluss darauf, was im Abfrage-Cache gespeichert wird.
- Die select-Funktion wird nur ausgeführt, wenn sich data geändert hat oder wenn sich die Referenz auf die select-Funktion selbst ändert. Um zu optimieren, packen Sie die Funktion in useCallback.
initialData: TData | () => TData
- Optional
- Wenn gesetzt, wird dieser Wert als anfängliche Daten für den Abfrage-Cache verwendet (solange die Abfrage noch nicht erstellt oder zwischengespeichert wurde).
- Wenn auf eine Funktion gesetzt, wird die Funktion **einmal** während der gemeinsamen/Stammabfrageinitialisierung aufgerufen und soll synchron die initialData zurückgeben.
- Anfängliche Daten gelten standardmäßig als veraltet, es sei denn, eine staleTime wurde festgelegt.
- initialData wird in den Cache **persistiert**.
initialDataUpdatedAt: number | (() => number | undefined)
- Optional
- Wenn gesetzt, wird dieser Wert als Zeitpunkt (in Millisekunden) verwendet, wann die initialData selbst zuletzt aktualisiert wurde.
placeholderData: TData | (previousValue: TData | undefined, previousQuery: Query | undefined) => TData
- Optional
- Wenn gesetzt, wird dieser Wert als Platzhalterdaten für diesen speziellen Abfragebeobachter verwendet, während die Abfrage noch im pending-Status ist.
- placeholderData wird **nicht** in den Cache **persistiert**.
- Wenn Sie eine Funktion für placeholderData angeben, erhalten Sie im ersten Argument die zuvor beobachteten Abfragedaten, falls verfügbar, und das zweite Argument ist die vollständige vorherige Abfrageinstanz.
structuralSharing: boolean | (oldData: unknown | undefined, newData: unknown) => unknown
- Optional
- Standardmäßig true
- Wenn auf false gesetzt, wird das strukturelle Teilen zwischen Abfrageergebnissen deaktiviert.
- Wenn auf eine Funktion gesetzt, werden die alten und neuen Datenwerte durch diese Funktion übergeben, die sie zu aufgelösten Daten für die Abfrage kombinieren sollte. Auf diese Weise können Sie Referenzen aus den alten Daten beibehalten, um die Leistung auch dann zu verbessern, wenn diese Daten nicht serialisierbare Werte enthalten.
subscribed: boolean
- Optional
- Standardmäßig true
- Wenn auf false gesetzt, wird diese Instanz von useQuery nicht mit dem Cache verbunden. Das bedeutet, dass sie die queryFn nicht von sich aus auslöst und keine Updates erhält, wenn Daten auf andere Weise in den Cache gelangen.
throwOnError: undefined | boolean | (error: TError, query: Query) => boolean
- Setzen Sie dies auf true, wenn Fehler in der Renderphase ausgelöst und an die nächste Fehlergrenze weitergegeben werden sollen.
- Setzen Sie dies auf false, um das Standardverhalten von suspense, Fehler an die Fehlergrenze zu werfen, zu deaktivieren.
- Wenn auf eine Funktion gesetzt, erhält diese den Fehler und die Abfrage und sollte einen booleschen Wert zurückgeben, der angibt, ob der Fehler in einer Fehlergrenze angezeigt werden soll (true) oder ob der Fehler als Status zurückgegeben werden soll (false).
meta: Record<string, unknown>
- Optional
- Wenn gesetzt, werden zusätzliche Informationen im Abfrage-Cache-Eintrag gespeichert, die nach Bedarf verwendet werden können. Sie sind dort verfügbar, wo die query verfügbar ist, und sind auch Teil des QueryFunctionContext, der der queryFn bereitgestellt wird.

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

status: QueryStatus
- Wird
  - pending sein, wenn keine zwischengespeicherten Daten vorhanden sind und noch kein Abfrageversuch abgeschlossen wurde.
  - error sein, wenn der Abfrageversuch zu einem Fehler geführt hat. Die entsprechende error-Eigenschaft enthält den Fehler, der beim Versuch des Abrufs empfangen wurde.
  - success sein, wenn die Abfrage eine Antwort ohne Fehler erhalten hat und bereit ist, ihre Daten anzuzeigen. Die entsprechende data-Eigenschaft der Abfrage sind die Daten, die vom erfolgreichen Abruf empfangen wurden, oder wenn die enabled-Eigenschaft der Abfrage auf false gesetzt ist und noch nicht abgerufen wurde, ist data die erste initialData, die der Abfrage bei der Initialisierung zugeführt wurde.
isPending: boolean
- Ein abgeleitetes boolesches Ergebnis der obigen status-Variable zur Bequemlichkeit.
isSuccess: boolean
- Ein abgeleitetes boolesches Ergebnis der obigen status-Variable zur Bequemlichkeit.
isError: boolean
- Ein abgeleitetes boolesches Ergebnis der obigen status-Variable zur Bequemlichkeit.
isLoadingError: boolean
- Ist true, wenn die Abfrage beim ersten Abruf fehlgeschlagen ist.
isRefetchError: boolean
- Ist true, wenn die Abfrage beim erneuten Abruf fehlgeschlagen ist.
data: TData
- Standardmäßig undefined.
- Die zuletzt erfolgreich aufgelösten Daten für die Abfrage.
dataUpdatedAt: number
- Der Zeitstempel, wann die Abfrage zuletzt den status als "success" zurückgegeben hat.
error: null | TError
- Standardmäßig null
- Das Fehlerobjekt für die Abfrage, wenn ein Fehler ausgelöst wurde.
errorUpdatedAt: number
- Der Zeitstempel, wann die Abfrage zuletzt den status als "error" zurückgegeben hat.
isStale: boolean
- Ist true, wenn die Daten im Cache ungültig gemacht wurden oder wenn die Daten älter als die angegebene staleTime sind.
isPlaceholderData: boolean
- Ist true, wenn die angezeigten Daten die Platzhalterdaten sind.
isFetched: boolean
- Ist true, wenn die Abfrage abgerufen wurde.
isFetchedAfterMount: boolean
- Ist true, wenn die Abfrage nach dem Mounten der Komponente abgerufen wurde.
- Diese Eigenschaft kann verwendet werden, um keine zuvor zwischengespeicherten Daten anzuzeigen.
fetchStatus: FetchStatus
- fetching: Ist true, wenn die queryFn ausgeführt wird, was sowohl das anfängliche pending als auch Hintergrund-Refetches einschließt.
- paused: Die Abfrage wollte abrufen, wurde aber paused.
- idle: Die Abfrage ruft nicht ab.
- Weitere Informationen finden Sie unter Netzwerkmodus.
isFetching: boolean
- Ein abgeleitetes boolesches Ergebnis der obigen fetchStatus-Variable zur Bequemlichkeit.
isPaused: boolean
- Ein abgeleitetes boolesches Ergebnis der obigen fetchStatus-Variable zur Bequemlichkeit.
isRefetching: boolean
- Ist true, wenn ein Hintergrund-Refetch in Bearbeitung ist, was anfängliche pending **nicht** einschließt.
- Ist dasselbe wie isFetching && !isPending
isLoading: boolean
- Ist true, wenn der erste Abruf einer Abfrage in Bearbeitung ist.
- Ist dasselbe wie isFetching && isPending
isInitialLoading: boolean
- veraltet
- Ein Alias für isLoading, wird in der nächsten Hauptversion entfernt.
isEnabled: boolean
- Ist true, wenn dieser Query-Observer aktiviert ist, andernfalls false.
failureCount: number
- Die Anzahl der Fehler für die Abfrage.
- Wird jedes Mal erhöht, wenn die Abfrage fehlschlägt.
- Wird auf 0 zurückgesetzt, wenn die Abfrage erfolgreich ist.
failureReason: null | TError
- Der Fehlergrund für die Wiederholung der Abfrage.
- Wird auf null zurückgesetzt, wenn die Abfrage erfolgreich ist.
errorUpdateCount: number
- Die Summe aller Fehler.
refetch: (options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise<UseQueryResult>
- Eine Funktion, um die Abfrage manuell erneut abzufragen.
- Wenn die Abfrage einen Fehler auslöst, wird der Fehler nur protokolliert. Wenn Sie möchten, dass ein Fehler ausgelöst wird, übergeben Sie die Option throwOnError: true.
- cancelRefetch?: boolean
  - Standardmäßig true
    - Standardmäßig wird eine aktuell laufende Anfrage abgebrochen, bevor eine neue Anfrage gestellt wird.
  - Wenn auf false gesetzt, erfolgt kein erneuter Abruf, wenn bereits eine Anfrage läuft.
promise: Promise<TData>
- Ein stabiles Promise, das mit den Daten der Abfrage aufgelöst wird.
- Erfordert, dass das Feature-Flag experimental_prefetchInRender auf dem QueryClient aktiviert ist.

Möchten Sie die Dokumentation überspringen?

Möchten Sie die Dokumentation überspringen?