GraphQL Fragments: benannt, inline und Typbedingungen | We.Inc
Baue GraphQL Fragments in einem Live-Query-Builder: benannte Fragments zur Wiederverwendung, Inline Fragments für Unions und Interfaces, Typbedingungen, __typename und Variablen.
Ein GraphQL Fragment ist eine benannte, wiederverwendbare Menge von Feldern für einen Typ, geschrieben als fragment Name on Type und mit ...Name in eine Query eingebunden. Ein Inline Fragment, geschrieben als ... on Type, hat keinen Namen und wählt Felder nur aus, wenn das Ergebnis genau dieser konkrete Typ ist. So fragst du Unions und Interfaces ab.
Formen von Fragments
Form
Syntax
Wofür du sie nutzt
Benanntes Fragment
fragment UserCard on User { ... }
Eine Feldliste in mehreren Queries teilen
Spread
...UserCard
Die Felder eines benannten Fragments einbinden
Inline Fragment
... on Photo { url }
Felder eines Mitglieds einer Union oder eines Interfaces
Inline ohne Typ
... @include(if: $full) { bio }
Eine Direktive auf eine Gruppe von Feldern anwenden
Typname
__typename
Union-Mitglieder in der Antwort unterscheiden
Hake im Builder die gewünschten Felder an, und er schreibt die Query für dich, einmal mit einem benannten Fragment und einmal mit den Feldern inline, damit du siehst, dass beide dieselben Daten abfragen. Schalte die Option für Suchergebnisse ein, um Inline Fragments über eine Union hinzuzufügen.
Hake die User-Felder an, die die Karte auf deinem Bildschirm anzeigt.
Wähle, ob die Felder in ein benanntes Fragment oder direkt in die Query kommen.
Schalte Suchergebnisse ein, um ein Union-Feld mit einem Inline Fragment pro Mitgliedstyp hinzuzufügen.
Kopiere die Query und führe sie gegen ein Schema aus, das diese Typen enthält.
Benenne Fragments nach der Komponente, die sie nutzt, etwa UserCard oder PostRow, damit jeder Teil des Bildschirms seinen eigenen Datenbedarf angibt.
Füge immer __typename hinzu, wenn du aus einer Union oder einem Interface auswählst. Dein Code braucht es, um zu wissen, welches Mitglied er bekommen hat.
Fragments können die Variablen der Operation lesen, ein Feld im Fragment kann also ein Argument wie size: $avatarSize erhalten.
Ein Fragment darf sich nicht selbst spreaden, weder direkt noch über ein anderes Fragment. Die Validierung lehnt den Zyklus ab, bevor irgendetwas läuft.
Häufige Fragen
Machen Fragments Antworten kleiner?
Nein. Ein Fragment ist eine Schreibhilfe für die Query. Der Server expandiert es, und die Antwort sieht genau so aus, als hättest du die Felder ausgeschrieben. Wählen zwei Spreads dasselbe Feld aus, erscheint es einmal.
Wann muss ich ein Inline Fragment verwenden?
Wenn ein Feld eine Union oder ein Interface zurückgibt und du Felder brauchst, die nur einige Mitgliedstypen haben. graphql.org zeigt das an einem hero, der ein Droid mit primaryFunction oder ein Human mit height sein kann.
Kann ein Fragment auf einem anderen Typ verwendet werden?
Nur dort, wo es passen kann. Ein Fragment auf einem Interface lässt sich in jedem Objekttyp spreaden, der es implementiert, aber ein Fragment auf User, das in einer Post-Auswahl gespreadet wird, besteht die Validierung nicht.
Wo stehen Fragments im Dokument?
Auf der obersten Ebene des Dokuments, neben den Operationen, in beliebiger Reihenfolge. Jedes definierte Fragment muss verwendet werden, sonst lehnt der Server das Dokument als ungültig ab.
Benannte Fragments zur Wiederverwendung
Angenommen, ein Profilkopf, ein Kommentar und eine Mitgliederliste zeigen alle einen Namen und einen Avatar. Diese Felder dreimal zu tippen lädt zum Auseinanderdriften ein: Eine Kopie bekommt ein Feld, das den anderen fehlt. Ein Fragment auf User hält die Liste an einer Stelle, und jede Query spreadet es.
Komponentenbasierte Apps gehen noch weiter. Jede Komponente deklariert das Fragment, das sie braucht, und die Seiten-Query spreadet die Fragments der Komponenten, die sie rendert. So liegt der Datenbedarf direkt neben dem Code, der ihn nutzt.
Inline Fragments und Typbedingungen
Der Teil on Type ist die Typbedingung. Bei einem benannten Fragment gibt sie an, zu welchem Typ die Felder gehören. Bei einem Inline Fragment in einem Union-Feld sorgt sie dafür, dass diese Felder nur gelten, wenn das Objekt diesen Typ hat.
Eine Suche, die Nutzer, Beiträge und Fotos zurückgibt, ist der klassische Fall. Die Auswahl listet ... on User, ... on Post und ... on Photo mit jeweils eigenen Feldern, und __typename sagt dem Client, welchen Zweig jedes Ergebnis genommen hat.
Schema, das der Builder verwendet
Eine Union für Suchergebnisse
SearchResult kann ein User oder ein Photo sein, daher braucht eine Auswahl darauf Inline Fragments, um an Felder eines der beiden Mitglieder zu kommen.
Eine Union-Antwort lesen
Was die Suche zurückgibt
Jedes Element enthält nur die Felder seines eigenen Zweigs, dazu __typename.
Verzweigen nach __typename
Der Typname ist der sichere Weg, die Mitglieder zu unterscheiden. Die Prüfung auf ein Feld kann brechen, wenn ein Typ dieses Feld später bekommt.
Fragment-Query-Builder
Auszuwählende User-Felder
Ein benanntes Fragment verwenden (UserCard)
Suchergebnisse hinzufügen (Union mit Inline Fragments)