Hooks useQuery et useMutation

La balise de modèle gql de @apollo/client analyse une chaîne de requête GraphQL en DocumentNode lors du chargement du module. Définissez les requêtes en dehors des composants : const GET_USERS = gql`query GetUsers { users { id name email } }`.

Remarque : dans le code de production, utilisez des chaînes entre apostrophes simples enveloppées par gql en tant que modèle balisé. La balise gql accepte une syntaxe de littéral de modèle dans le code source JavaScript.

useQuery(GET_USERS) renvoie { loading, error, data, refetch, fetchMore, networkStatus }. loading vaut true pendant la récupération initiale. error contient les erreurs GraphQL ou réseau éventuelles. data contient le résultat de la requête correspondant à sa structure.

Vérifiez d'abord loading et error avant d'accéder à data afin d'éviter d'afficher des valeurs nulles.

Affichez un composant squelette tant que loading vaut true. Affichez un message d'erreur si error est défini (accédez à error.message pour obtenir le texte de l'erreur). N'affichez le contenu réel que lorsque data est défini et loading vaut false.

Ce schéma à trois états (loading / error / data) constitue la structure standard d'un composant Apollo Client.

L'objet data reproduit la structure de la requête GraphQL. Pour query { users { id name } }, accédez à data.users, qui est un tableau d'objets {id, name}. Les types TypeScript correspondent si vous utilisez graphql-codegen pour générer des hooks typés.

Sans graphql-codegen, data est typé comme any. Avec graphql-codegen, useQuery renvoie automatiquement des données entièrement typées.

Transmettez les variables comme deuxième argument : useQuery(GET_USER, { variables: { id: userId } }). La requête est automatiquement réexécutée lorsque userId change, comme avec un tableau de dépendances de useEffect.

Apollo Client met en cache séparément chaque combinaison unique de requête et de variables ; ainsi, GET_USER avec id: "1" et GET_USER avec id: "2" possèdent des entrées de cache indépendantes.

Transmettez skip: true dans les options pour empêcher l'exécution de la requête : useQuery(GET_USER, { skip: !userId }). Apollo n'envoie pas la requête lorsque skip vaut true ; loading vaut false et data vaut undefined.

C'est l'équivalent Apollo de la clé null de SWR et de l'option enabled: false de React Query.

La fonction refetch renvoyée par useQuery déclenche une requête réseau quelle que soit la politique de récupération. Appelez refetch() après une action utilisateur susceptible d'avoir modifié les données du serveur, par exemple après la soumission d'un formulaire.

Transmettez de nouvelles variables à refetch : refetch({ id: newId }) pour effectuer une nouvelle récupération avec des paramètres différents.

Transmettez notifyOnNetworkStatusChange: true dans les options pour recevoir des mises à jour lorsque l'état du réseau change (récupération, nouvelle récupération, interrogation périodique, etc.). Le champ networkStatus contient un code numérique de l'énumération NetworkStatus.

Cela permet d'afficher un indicateur discret de « mise à jour » lorsqu'une nouvelle récupération en arrière-plan est en cours, sans masquer les données actuelles.

useMutation(CREATE_USER) renvoie [mutateFunction, { loading, error, data, reset }]. La fonction de mutation est appelée lorsque l'utilisateur envoie un formulaire. Elle renvoie une Promise contenant { data, errors }.

Appelez mutate({ variables: { name: 'Alice', email: 'alice@example.com' } }) pour transmettre les données d'entrée à la mutation.

Transmettez onCompleted: (data) => navigate('/dashboard') et onError: (error) => showToast(error.message) aux options de useMutation. Ces fonctions de rappel sont exécutées une fois la mutation résolue ou rejetée.

onCompleted reçoit les données du résultat de la mutation, ce qui est utile pour déclencher une navigation, afficher des messages de réussite ou réinitialiser des formulaires.

L'option optimisticResponse dans l'appel à mutate écrit immédiatement un résultat synthétique dans le cache, avant la réponse du serveur. Apollo affiche instantanément les données optimistes, puis les remplace par la réponse réelle du serveur dès son arrivée.

Si la mutation échoue, Apollo restaure automatiquement l'état du cache antérieur à l'optimisme, ce qui maintient la cohérence de l'interface.

Que devient un appel à useQuery lorsqu'on lui transmet skip: true ?

Définissez les requêtes avec la balise gql, appelez useQuery(QUERY, { variables, skip }) et gérez les états loading/error/data. useMutation renvoie une fonction de déclenchement et un objet d'état ; appelez cette fonction avec des variables et gérez les résultats via onCompleted et onError. Les réponses optimistes mettent immédiatement à jour le cache, avec une restauration automatique en cas d'échec.

L'option skip et la nouvelle récupération déclenchée par les variables permettent de gérer le chargement conditionnel et paramétré des données.