useQuery- und useMutation-Hooks

Der gql-Template-Tag aus @apollo/client parst eine GraphQL-Abfragezeichenfolge beim Laden des Moduls in einen DocumentNode. Definieren Sie Queries außerhalb von Komponenten: const GET_USERS = gql`query GetUsers { users { id name email } }`.

Beachten Sie: Verwenden Sie im Produktionscode von gql umschlossene Zeichenfolgen in einfachen Anführungszeichen als getaggtes Template. Der gql-Tag akzeptiert in JavaScript-Quelltext die Syntax eines Template-Literals.

useQuery(GET_USERS) liefert { loading, error, data, refetch, fetchMore, networkStatus }. loading ist während des ersten Abrufs true. error enthält alle GraphQL- oder Netzwerkfehler. data enthält das Abfrageergebnis entsprechend der Abfragestruktur.

Prüfen Sie loading und error zuerst, bevor Sie auf data zugreifen, um das Rendern von null-Werten zu vermeiden.

Rendern Sie eine Skeleton-Komponente, solange loading true ist. Rendern Sie eine Fehlermeldung, wenn error definiert ist (greifen Sie für den Fehlertext auf error.message zu). Rendern Sie den eigentlichen Inhalt nur, wenn data definiert und loading false ist.

Dieses Drei-Zustände-Muster (loading / error / data) ist die standardmäßige Struktur für Apollo-Client-Komponenten.

Das data-Objekt bildet die Struktur der GraphQL-Query ab. Bei query { users { id name } } greifen Sie über data.users auf ein Array von Objekten mit {id, name} zu. Die TypeScript-Typen stimmen überein, wenn Sie graphql-codegen zum Generieren typisierter Hooks verwenden.

Ohne Codegen wird data als any typisiert. Mit Codegen liefert useQuery automatisch vollständig typisierte Daten.

Übergeben Sie Variablen als zweites Argument: useQuery(GET_USER, { variables: { id: userId } }). Die Query wird automatisch erneut ausgeführt, wenn sich userId ändert, genau wie bei einem useEffect-Abhängigkeitsarray.

Apollo Client cached jede eindeutige Kombination aus Query und Variablen separat. Daher haben GET_USER mit id: "1" und GET_USER mit id: "2" unabhängige Cache-Einträge.

Übergeben Sie skip: true in den Optionen, um die Ausführung der Query zu verhindern: useQuery(GET_USER, { skip: !userId }). Apollo sendet keine Anfrage, wenn skip true ist; loading ist false und data ist undefined.

Dies entspricht bei Apollo dem null key von SWR und der Option enabled: false von React Query.

Die von useQuery zurückgegebene refetch-Funktion löst unabhängig von der Fetch-Policy eine Netzwerkanfrage aus. Rufen Sie refetch() nach einer Benutzeraktion auf, die die Serverdaten geändert haben könnte, beispielsweise nach dem Absenden eines Formulars.

Übergeben Sie refetch neue Variablen: refetch({ id: newId }), um den erneuten Abruf mit anderen Parametern durchzuführen.

Übergeben Sie notifyOnNetworkStatusChange: true in den Optionen, um Aktualisierungen zu erhalten, wenn sich der Netzwerkstatus ändert (fetching, refetching, polling usw.). Das Feld networkStatus enthält einen numerischen Code aus dem NetworkStatus-Enum.

Damit können Sie eine dezente Anzeige wie „Wird aktualisiert“ einblenden, während ein erneuter Abruf im Hintergrund läuft, ohne die aktuellen Daten auszublenden.

useMutation(CREATE_USER) liefert [mutateFunction, { loading, error, data, reset }]. Die mutate-Funktion wird aufgerufen, wenn der Benutzer ein Formular absendet. Sie gibt ein Promise mit { data, errors } zurück.

Rufen Sie mutate({ variables: { name: 'Alice', email: 'alice@example.com' } }) auf, um Eingaben an die Mutation zu übergeben.

Übergeben Sie onCompleted: (data) => navigate('/dashboard') und onError: (error) => showToast(error.message) an die Optionen von useMutation. Diese Callbacks werden ausgelöst, nachdem die Mutation erfolgreich abgeschlossen oder abgelehnt wurde.

onCompleted erhält die Ergebnisdaten der Mutation und eignet sich zum Auslösen einer Navigation, zum Anzeigen von Erfolgsmeldungen oder zum Zurücksetzen von Formularen.

Die Option optimisticResponse im mutate-Aufruf schreibt sofort ein synthetisches Ergebnis in den Cache, bevor der Server antwortet. Apollo rendert die optimistischen Daten sofort und ersetzt sie durch die echte Serverantwort, sobald diese eintrifft.

Wenn die Mutation fehlschlägt, setzt Apollo den Cache automatisch auf den Zustand vor der optimistischen Aktualisierung zurück, sodass die Benutzeroberfläche konsistent bleibt.

Was geschieht bei useQuery, wenn skip: true übergeben wird?

Definieren Sie Queries mit dem gql-Tag, rufen Sie useQuery(QUERY, { variables, skip }) auf und behandeln Sie die Zustände loading, error und data. useMutation liefert eine Trigger-Funktion und ein Statusobjekt; rufen Sie die Funktion mit Variablen auf und verarbeiten Sie die Ergebnisse über onCompleted und onError. Optimistische Antworten aktualisieren den Cache sofort und werden bei einem Fehler automatisch zurückgerollt.

Die Option skip und das durch Variablen gesteuerte erneute Abrufen ermöglichen das bedingte und parametrisierte Laden von Daten.