Fragments GraphQL : nommés, inline et conditions de type | We.Inc
Créez des fragments GraphQL dans un constructeur de requêtes en direct : fragments nommés pour la réutilisation, fragments inline pour les unions et interfaces, conditions de type, __typename et variables.
Un fragment GraphQL est un ensemble nommé et réutilisable de champs pour un type, écrit fragment Name on Type et inclus dans une requête avec ...Name. Un fragment inline, écrit ... on Type, n'a pas de nom et ne sélectionne des champs que lorsque le résultat est de ce type concret : c'est ainsi que l'on interroge les unions et les interfaces.
Formes de fragments
Forme
Syntaxe
À utiliser pour
Fragment nommé
fragment UserCard on User { ... }
Partager une liste de champs entre plusieurs requêtes
Spread
...UserCard
Inclure les champs d'un fragment nommé
Fragment inline
... on Photo { url }
Les champs d'un membre d'une union ou d'une interface
Inline sans type
... @include(if: $full) { bio }
Appliquer une directive à un groupe de champs
Nom du type
__typename
Distinguer les membres d'une union dans la réponse
Cochez les champs voulus dans le constructeur et il écrit la requête pour vous, une fois avec un fragment nommé et une fois avec les champs écrits directement, pour que vous constatiez qu'elles demandent les mêmes données. Activez l'option des résultats de recherche pour ajouter des fragments inline sur une union.
Cochez les champs User qu'affiche la carte de votre écran.
Choisissez si les champs vont dans un fragment nommé ou directement dans la requête.
Activez les résultats de recherche pour ajouter un champ union avec un fragment inline par type membre.
Copiez la requête et exécutez-la sur un schéma qui contient ces types.
Nommez les fragments d'après le composant qui les utilise, comme UserCard ou PostRow, afin que chaque partie de l'écran déclare ses propres besoins en données.
Ajoutez toujours __typename quand vous sélectionnez depuis une union ou une interface ; votre code en a besoin pour savoir quel membre il a reçu.
Les fragments peuvent lire les variables de l'opération, un champ de fragment peut donc prendre un argument comme size: $avatarSize.
Un fragment ne peut pas s'inclure lui-même, directement ou via un autre fragment. La validation rejette le cycle avant toute exécution.
Questions fréquentes
Les fragments réduisent-ils la taille des réponses ?
Non. Un fragment est une aide à l'écriture de la requête. Le serveur le développe, et la réponse est exactement la même que si vous aviez écrit les champs en entier. Si deux spreads sélectionnent le même champ, il n'apparaît qu'une fois.
Quand dois-je utiliser un fragment inline ?
Quand un champ renvoie une union ou une interface et que vous avez besoin de champs que seuls certains types membres possèdent. graphql.org l'illustre avec un hero qui peut être un Droid avec primaryFunction ou un Human avec height.
Un fragment peut-il être utilisé sur un autre type ?
Uniquement là où il peut s'appliquer. Un fragment sur une interface peut être inclus dans n'importe quel type objet qui l'implémente, mais un fragment sur User inclus dans une sélection de Post échoue à la validation.
Où placer les fragments dans le document ?
Au niveau supérieur du document, à côté des opérations, dans n'importe quel ordre. Chaque fragment défini doit être utilisé, sinon le serveur rejette le document comme invalide.
Des fragments nommés pour la réutilisation
Imaginez qu'un en-tête de profil, un commentaire et une liste de membres affichent tous un nom et un avatar. Écrire ces champs trois fois favorise les divergences : une copie gagne un champ que les autres n'ont pas. Un fragment sur User contient la liste une seule fois et chaque requête l'inclut.
Les applications à base de composants vont plus loin. Chaque composant déclare le fragment dont il a besoin, et la requête de la page inclut les fragments des composants qu'elle affiche, si bien que les besoins en données vivent à côté du code qui les utilise.
Fragments inline et conditions de type
La partie on Type est la condition de type. Pour un fragment nommé, elle indique à quel type appartiennent les champs. Pour un fragment inline dans un champ union, elle fait en sorte que ces champs ne s'appliquent que si l'objet est de ce type.
Une recherche qui renvoie des utilisateurs, des articles et des photos est le cas classique. La sélection liste ... on User, ... on Post et ... on Photo, chacun avec ses propres champs, et __typename indique au client quelle branche chaque résultat a suivie.
Schéma utilisé par le constructeur
Une union pour les résultats de recherche
SearchResult peut être un User ou une Photo, une sélection sur ce type a donc besoin de fragments inline pour atteindre les champs de l'un ou l'autre membre.
Lire une réponse d'union
Ce que renvoie la recherche
Chaque élément ne porte que les champs de sa propre branche, plus __typename.
Brancher sur __typename
Le nom du type est la manière sûre de distinguer les membres ; tester la présence d'un champ peut casser si un type gagne ce champ plus tard.
Constructeur de requêtes avec fragments
Champs User à sélectionner
Utiliser un fragment nommé (UserCard)
Ajouter des résultats de recherche (union avec fragments inline)
Requête
Copier la requête
{n} champ(s) sélectionné(s), {v} ligne(s) de requête