Hook useQuery e useMutation

Il tag template gql di @apollo/client analizza una stringa di query GraphQL trasformandola in un DocumentNode al caricamento del modulo. Definisca le query all'esterno dei componenti: const GET_USERS = gql`query GetUsers { users { id name email } }`.

Nota: nel codice di produzione, utilizzi stringhe racchiuse tra apici singoli e avvolte da gql come template tag. Il tag gql accetta la sintassi di un template literal nel codice sorgente JavaScript.

useQuery(GET_USERS) restituisce { loading, error, data, refetch, fetchMore, networkStatus }. loading è true durante il recupero iniziale. error contiene eventuali errori GraphQL o di rete. data contiene il risultato della query, corrispondente alla forma della query.

Controlli prima loading ed error, prima di accedere a data, per evitare di eseguire il rendering di valori null.

Esegua il rendering di un componente skeleton mentre loading è true. Esegua il rendering di un messaggio di errore se error è definito, accedendo a error.message per ottenere il testo dell'errore. Esegua il rendering del contenuto effettivo solo quando data è definito e loading è false.

Questo pattern a tre stati (loading / error / data) è la struttura standard dei componenti Apollo Client.

L'oggetto data rispecchia la struttura della query GraphQL. Per query { users { id name } }, acceda a data.users, che è un array di oggetti {id, name}. I tipi TypeScript corrispondono se usa graphql-codegen per generare hook tipizzati.

Senza codegen, data ha tipo any. Con codegen, useQuery restituisce automaticamente dati completamente tipizzati.

Passi le variabili come secondo argomento: useQuery(GET_USER, { variables: { id: userId } }). La query viene eseguita nuovamente quando userId cambia, proprio come un array di dipendenze di useEffect.

Apollo Client memorizza nella cache separatamente ogni combinazione univoca di query + variables, quindi GET_USER con id: "1" e GET_USER con id: "2" hanno voci indipendenti nella cache.

Passi skip: true nelle opzioni per impedire l'esecuzione della query: useQuery(GET_USER, { skip: !userId }). Apollo non invia la richiesta quando skip è true; loading è false e data è undefined.

Questa è l'equivalente Apollo della chiave null di SWR e dell'opzione enabled: false di React Query.

La funzione refetch restituita da useQuery attiva una richiesta di rete indipendentemente dalla fetch policy. Chiami refetch() dopo un'azione dell'utente che potrebbe aver modificato i dati sul server, ad esempio dopo l'invio di un modulo.

Passi nuove variabili a refetch: refetch({ id: newId }) per eseguire nuovamente la richiesta con parametri diversi.

Passi notifyOnNetworkStatusChange: true nelle opzioni per ricevere aggiornamenti quando cambia lo stato della rete, ad esempio durante il recupero, il refetch o il polling. Il campo networkStatus contiene un codice numerico dell'enum NetworkStatus.

In questo modo può mostrare un indicatore discreto di "aggiornamento" mentre è in corso un refetch in background, senza nascondere i dati correnti.

useMutation(CREATE_USER) restituisce [mutateFunction, { loading, error, data, reset }]. La funzione mutate viene chiamata quando l'utente invia un modulo. Restituisce una Promise con { data, errors }.

Chiami mutate({ variables: { name: 'Alice', email: 'alice@example.com' } }) per passare l'input alla mutation.

Passi onCompleted: (data) => navigate('/dashboard') e onError: (error) => showToast(error.message) alle opzioni di useMutation. Queste callback vengono eseguite quando la mutation viene completata o rifiutata.

onCompleted riceve i dati del risultato della mutation, utili per avviare la navigazione, visualizzare messaggi di successo o reimpostare i moduli.

L'opzione optimisticResponse nella chiamata a mutate scrive immediatamente nella cache un risultato sintetico, prima che il server risponda. Apollo esegue subito il rendering dei dati ottimistici, quindi li sostituisce con la risposta effettiva del server quando arriva.

Se la mutation non riesce, Apollo ripristina automaticamente lo stato della cache precedente alla risposta ottimistica, mantenendo coerente l'interfaccia.

Che cosa accade a useQuery quando viene passato skip: true?

Definisca le query con il tag gql, chiami useQuery(QUERY, { variables, skip }) e gestisca gli stati loading/error/data. useMutation restituisce una funzione di attivazione e un oggetto di stato; la chiami con le variabili e gestisca i risultati tramite onCompleted e onError. Le risposte ottimistiche aggiornano immediatamente la cache, con ripristino automatico in caso di errore.

L'opzione skip e il nuovo recupero guidato dalle variabili gestiscono il caricamento condizionale e parametrizzato dei dati.