Fragments de GraphQL: con nombre, inline y condiciones de tipo | We.Inc
Crea fragments de GraphQL en un generador de consultas en vivo: fragments con nombre para reutilizar, fragments inline para uniones e interfaces, condiciones de tipo, __typename y variables.
Un fragment de GraphQL es un conjunto de campos con nombre y reutilizable para un tipo, escrito como fragment Name on Type e incluido en una consulta con ...Name. Un fragment inline, escrito ... on Type, no tiene nombre y selecciona campos solo cuando el resultado es ese tipo concreto, que es como se consultan las uniones y las interfaces.
Formas de los fragments
Forma
Sintaxis
Para qué sirve
Fragment con nombre
fragment UserCard on User { ... }
Compartir una lista de campos entre consultas
Spread
...UserCard
Incluir los campos de un fragment con nombre
Fragment inline
... on Photo { url }
Campos de un miembro de una unión o interfaz
Inline sin tipo
... @include(if: $full) { bio }
Aplicar una directiva a un grupo de campos
Nombre del tipo
__typename
Distinguir los miembros de una unión en la respuesta
Marca los campos que quieres en el generador y escribirá la consulta por ti, una vez con un fragment con nombre y otra con los campos escritos directamente, para que veas que piden los mismos datos. Activa la opción de resultados de búsqueda para añadir fragments inline sobre una unión.
Marca los campos de User que muestra la tarjeta de tu pantalla.
Elige si los campos van en un fragment con nombre o directamente en la consulta.
Activa los resultados de búsqueda para añadir un campo de unión con un fragment inline por cada tipo miembro.
Copia la consulta y ejecútala contra un esquema que tenga estos tipos.
Pon a los fragments el nombre del componente que los usa, como UserCard o PostRow, para que cada parte de la pantalla declare sus propias necesidades de datos.
Añade siempre __typename cuando selecciones desde una unión o una interfaz; tu código lo necesita para saber qué miembro recibió.
Los fragments pueden leer las variables de la operación, así que un campo de un fragment puede recibir un argumento como size: $avatarSize.
Un fragment no puede hacer spread de sí mismo, ni directamente ni a través de otro fragment. La validación rechaza el ciclo antes de que se ejecute nada.
Preguntas frecuentes
¿Los fragments hacen más pequeñas las respuestas?
No. Un fragment es una ayuda para escribir la consulta. El servidor lo expande, y la respuesta es exactamente igual que si hubieras escrito los campos a mano. Si dos spreads seleccionan el mismo campo, aparece una sola vez.
¿Cuándo tengo que usar un fragment inline?
Cuando un campo devuelve una unión o una interfaz y necesitas campos que solo tienen algunos de los tipos miembro. graphql.org lo muestra con un hero que puede ser un Droid con primaryFunction o un Human con height.
¿Se puede usar un fragment en otro tipo?
Solo donde pueda aplicarse. Un fragment sobre una interfaz se puede usar con spread dentro de cualquier tipo de objeto que la implemente, pero un fragment sobre User usado dentro de una selección de Post no pasa la validación.
¿Dónde van los fragments en el documento?
En el nivel superior del documento, junto a las operaciones, en cualquier orden. Todo fragment definido debe usarse, o el servidor rechaza el documento por no ser válido.
Fragments con nombre para reutilizar
Imagina que una cabecera de perfil, un comentario y una lista de miembros muestran un nombre y un avatar. Escribir esos campos tres veces invita a que diverjan: una copia gana un campo que las otras no tienen. Un fragment sobre User guarda la lista una sola vez y cada consulta la incluye con spread.
Las aplicaciones basadas en componentes van más allá. Cada componente declara el fragment que necesita, y la consulta de la página incluye los fragments de los componentes que muestra, así que las necesidades de datos viven junto al código que las usa.
Fragments inline y condiciones de tipo
La parte on Type es la condición de tipo. En un fragment con nombre indica a qué tipo pertenecen los campos. En un fragment inline dentro de un campo de unión, hace que esos campos se apliquen solo cuando el objeto es de ese tipo.
Una búsqueda que devuelve usuarios, publicaciones y fotos es el caso clásico. La selección incluye ... on User, ... on Post y ... on Photo, cada uno con sus propios campos, y __typename le dice al cliente qué rama tomó cada resultado.
Esquema que usa el generador
Una unión para los resultados de búsqueda
SearchResult puede ser un User o una Photo, así que una selección sobre él necesita fragments inline para llegar a los campos de cualquiera de los dos miembros.
Cómo leer una respuesta de unión
Lo que devuelve la búsqueda
Cada elemento lleva solo los campos de su propia rama, más __typename.
Ramificar según __typename
El nombre del tipo es la forma segura de distinguir los miembros; comprobar si existe un campo puede fallar cuando un tipo lo gane más adelante.
Generador de consultas con fragments
Campos de User que seleccionar
Usar un fragment con nombre (UserCard)
Añadir resultados de búsqueda (unión con fragments inline)
Consulta
Copiar consulta
{n} campo(s) seleccionado(s), {v} línea(s) de consulta