Die Mächtigkeit von virtuellen Feldern in Payload CMS

Wenn Sie mit Payload CMS arbeiten, möchten Sie manchmal Werte in Ihrer API bereitstellen, die nicht manuell von einem Benutzer eingegeben oder persistent in Ihrer Datenbank gespeichert sind. Stattdessen werden diese Werte spontan berechnet oder abgeleitet aus anderen Daten. Hier kommen virtuelle Felder ins Spiel.

In diesem Artikel werden wir behandeln, was virtuelle Felder sind, wie und wann man sie verwendet, und praktische Beispiele aus der realen Welt geben.

Was sind virtuelle Felder?

Virtuelle Felder in Payload CMS sind dynamisch berechnete Felder, die nicht in der Datenbank gespeichert werden. Stattdessen werden sie während des Lesevorgangs des Dokuments mit dem afterRead-Hook befüllt. Dieser Hook wird ausgeführt, nachdem das Dokument aus der Datenbank gelesen wurde, aber bevor es an den Aufrufer zurückgegeben wird, weshalb er der perfekte Ort ist, um abgeleitete oder berechnete Daten einzufügen.

Da virtuelle Felder nicht in der Datenbank existieren, sind sie schreibgeschützt, nicht abfragbar, können nicht für das Filtern oder Sortieren verwendet werden und sind nicht berechtigt, als useAsTitle verwendet zu werden.

Wie macht man ein Feld in Payload CMS virtuell?

Seit Payload v3.0.0 können Sie ein virtuelles Feld definieren, indem Sie die virtual: true Eigenschaft zur Feldkonfiguration hinzufügen. Dies teilt Payload mit, dass das Feld nicht in der Datenbank gespeichert werden soll. Sein Wert kann dann dynamisch befüllt werden, typischerweise mit einem afterRead Hook.

Wie man den Wert virtueller Felder festlegt

Es gibt zwei gängige Möglichkeiten, virtuelle Felder in Payload CMS zu befüllen, abhängig von Ihrem Anwendungsfall:

Über einen Feld-Hook

Dies ist der gebräuchlichste und einfachste Ansatz, ideal, wenn Sie den Wert eines einzelnen virtuellen Feldes festlegen. Die Logik bleibt im afterRead-Hook innerhalb der Felddefinition gekapselt.

{
  name: 'virtual-field',
  type: 'text',
  virtual: true,
  hooks: {
    afterRead: [
      ({ siblingData, req }) {
        // Compute the virtual field data. 
        // Here you have access to the sibling field data, Payload request and more.
      },
    ],
  },
}

Über einen Collection-Hook

Diese Methode ist nützlich, wenn Sie mehrere virtuelle Felder festlegen müssen, die von einer gemeinsamen Logik oder verwandten Daten abhängen. Wenn Sie beispielsweise ein Slug- und ein Parent-Feld im Dokument gespeichert haben und ein virtuelles Path- und ein AlternatePaths-Feld ableiten möchten, ist es sinnvoll, einen beforeRead- oder afterRead-Collection-Hook zu verwenden und sie gemeinsam zu berechnen.

⚠️ Hinweis: Bei Hooks auf Sammlungsebene wie afterRead sollten Sie zunächst prüfen, ob ein bestimmtes virtuelles Feld angefordert (ausgewählt) wurde. Dadurch wird sichergestellt, dass keine unnötigen Werte berechnet werden, wenn das Feld nicht benötigt wird.

Anwendungsfälle

Virtuelle Felder sind besonders nützlich, wenn Sie Ihr Dokument um Werte erweitern wollen, die dynamisch berechnet oder abgeleitet werden können, ohne sie in Ihrer Datenbank zu speichern. Im Folgenden finden Sie einige der häufigsten und praktischsten Szenarien:

Kombinieren von Daten aus nicht-virtuellen Feldern

Der einfachste und häufigste Anwendungsfall ist die Kombination vorhandener Felder innerhalb desselben Dokuments.

Beispiel: Kombinieren von Vor- und Nachname

Hier ist ein einfaches Beispiel, das einen vollständigen Namen auf der Grundlage von zwei vorhandenen Feldern erzeugt: Vorname und Nachname.

{
  name: 'fullName',
  type: 'text',
  virtual: true,
  hooks: {
    afterRead: [
      ({ siblingData }) => {
        return `${siblingData.firstName} ${siblingData.lastName}`;
      },
    ],
  },
}

Dies ist in vielen realen Szenarien nützlich, z. B. in Benutzerprofilen, Autorenanzeigen oder Kontaktlisten, wo es von Vorteil ist, wenn der vollständige Name automatisch berechnet wird.

Berechnungen auf der Grundlage bestehender Felder

Ein weiteres häufiges Muster ist die Durchführung einfacher Berechnungen anhand von Feldwerten aus den Daten eines Geschwisterfelds.

Beispiel: Geschätzte Lesedauer für Blogbeiträge

Angenommen, Sie erstellen einen Blog und möchten den Lesern zeigen, wie lange es dauert, jeden Beitrag zu lesen. Anstatt diesen Wert manuell einzugeben, können Sie ihn mit Hilfe eines virtuellen Feldes aus dem Inhalt des Beitrags berechnen.

{
  name: 'estimatedReadingTime',
  type: 'number',
  virtual: true,
  hooks: {
    afterRead: [
      ({ siblingData }) => {
        const contentString = siblingData.content
          ? convertLexicalToPlaintext({ data: siblingData.content })
          : '';

        const wordCount = contentString.trim().split(/\s+/).length;
        const wordsPerMinute = 238;
        const readingTime = Math.ceil(wordCount / wordsPerMinute);

        return readingTime;
      },
    ],
  },
}

In diesem Beispiel ist convertLexicalToPlaintext eine von Payload angebotene Utility-Funktion , die Ihre Rich-Text- oder Lexical-Editor-Inhalte zur Analyse in einfachen Text umwandelt.

Zusammenführen oder Einspeisen von internen oder externen Daten (asynchrone virtuelle Felder)

Zu den fortgeschritteneren Anwendungsfällen gehört die asynchrone Anreicherung von Dokumenten mit Daten aus anderen Sammlungen oder externen APIs.

{
  name: 'weatherData',
  type: 'json',
  virtual: true,
  hooks: {
    afterRead: [
      async ({ siblingData }) => {
        const res = await fetch(`https://weatherapi.com/forecast?city=${siblingData.city}`)
        const weather = await res.json()
        return weather
      },
    ],
  },
}

Ideal für Anwendungsfälle wie das Abrufen der neuesten Wechselkurse, die Anzeige von Echtzeit-Wetterbedingungen auf der Grundlage eines Standortfeldes oder die Anzeige verwandter Daten aus einer anderen Sammlung, die im Wesentlichen als leichtgewichtige Fremddaten-Wrapper zur Anreicherung von Dokumenten während des Lesens dienen.

Gut zu wissen bei der Verwendung virtueller Felder

• virtual: true allein macht ein Feld nicht schreibgeschützt, verwenden Sie admin.readOnly: true, um zu verhindern, dass Benutzer ungespeicherte Werte in das Verwaltungsfenster eingeben.
• Virtuelle Felder, die sich ausschließlich auf einen afterRead-Hook verlassen, um Daten auf der Grundlage eines anderen Feldes aufzufüllen, zeigen keinen Wert an, wenn ein neues Dokument erstellt wird, und werden im Verwaltungsbereich nicht live aktualisiert, wenn sich das Quellfeld ändert. Verwenden Sie eine benutzerdefinierte Komponente, um das Echtzeitverhalten zu aktivieren.
• Wenn sie als required markiert sind, können virtuelle Felder fehlschlagen, wenn der afterRead-Hook noch nicht ausgeführt wurde, deaktivieren Sie die Validierung mit validate: () => true.

Warum virtuelle Felder verwenden?

Virtuelle Felder bieten eine elegante Möglichkeit, Ihre Dokumente mit dynamisch generierten Feldern zu erweitern, die auf anderen Daten basieren. Sie sind ideal, wenn Sie statische Daten von dynamisch abgeleiteten Werten trennen möchten, damit Ihre Datenbank schlank bleibt und sich auf rohe, vom Benutzer verwaltete Inhalte konzentriert.

Wichtige Vorteile:

• Immer synchron: Virtuelle Felder werden zur Laufzeit berechnet und spiegeln immer den aktuellen Stand der Quelldaten wider. Kein manuelles Neuberechnen notwendig.
• Ideal für reine Anzeigezwecke: Perfekt für Felder, die nur im Frontend angezeigt werden sollen (z. B. Labels oder Zusammenfassungen) – und damit alles zentral im CMS bleibt.
• Klare Trennung von Verantwortung: Virtuelle Felder helfen dabei, statische Inhalte von berechneten Werten sauber zu trennen.
• Ideal für schreibgeschützte Ableitungen: Praktisch für Dinge wie vollständige Namen, Lesezeit oder Slugs, die sich automatisch aus anderen Feldern ergeben und nicht bearbeitet werden müssen.

Wann man keine virtuellen Felder verwenden sollte

So hilfreich virtuelle Felder auch sind – es gibt Fälle, in denen sie ungeeignet sind:

• Notwendigkeit zum filtern oder sortieren: Virtuelle Felder werden nicht gespeichert und können daher nicht in Abfragen verwendet werden.
• Der Wert soll dauerhaft bestehen bleiben: Wenn sich ein Wert historisch nicht verändern darf (z. B. Lesezeit zum Veröffentlichungszeitpunkt), ist ein virtuelles Feld ungeeignet.
• Komplexe oder asynchrone Berechnungen: Aufwändige Berechnungen oder externe API-Aufrufe können die Ladezeit bei großen Datenmengen deutlich verlangsamen.

Alternativen zu virtuellen Feldern

• Gespeicherte abgeleitete Felder mit Sync-Logik: Werte wie Lesezeit können gespeichert und bei Änderungen per Hook (beforeChange, afterChange) aktualisiert werden. Dadurch sind sie filter- und sortierbar – aber es braucht eine Synchronisationslogik.
• Manuell bearbeitbare Felder mit Auto-Fill: Wenn ein Wert manchmal manuell überschrieben werden soll, kann ein normales Feld mit optionaler Vorbelegung sinnvoller sein.

Relationship Virtual Fields

Mit Payload v3.35.0  wurde eine neue Funktion eingeführt: Virtuelle Felder können nun direkt mit einem bestimmten Feld eines verknüpften Dokuments verknüpft werden – ohne redundante Speicherung.

Was sind Relationship Virtual Fields?

Ein Relationship Virtual Field erlaubt es, ein Feld aus einem verknüpften Dokument (z. B. über ein relationship- oder upload-Feld) auszulesen und es im aktuellen Dokument bereitzustellen – ohne es zu speichern.

Besonders: Dieses Feld wird immer mit dem verknüpften Wert gefüllt – auch bei depth: 0. Im Gegensatz zu regulären virtuellen Feldern können Relationship Virtual Fields sogar gefiltert und sortiert werden.

Virtuelle Felder „extrahieren sich“ gewissermaßen gezielt ein bestimmtes Feld aus einem verknüpften Dokument – sogar tief verschachtelte Felder wie person.location.city.

Im folgenden Beispiel referenziert jedes Dokument in der Collection authors einen Eintrag aus der Collection persons über das Feld person. Das virtuelle Feld name übernimmt automatisch den Wert von person.title:

{
  slug: 'authors',
  admin: {
    useAsTitle: 'name'
  },
  fields: [
    {
      type: 'relationship',
      name: 'person',
      relationTo: 'persons',
    },
    {
      type: 'text',
      name: 'name',
      virtual: 'person.title',
    },
  ],
},

Wann Relationship Virtual Fields sinnvoll sind

Setzen Sie ein Relationship Virtual Fields ein, wenn Sie:

• ein bestimmtes Feld aus einem verknüpften Dokument (z. B. category.title) anzeigen möchten, ohne die Daten zu duplizieren.
• Dokumente basierend auf einem Feld aus einem verknüpften Dokument filtern oder sortieren möchten.
• ein Feld aus einem verknüpften Dokument als Titel des aktuellen Dokuments über useAsTitle verwenden möchten.

⚠️ Hinweis: Das genutzte Relationship-Feld muss eine einfache, nicht-polymorphe Beziehung sein. Felder mit hasMany: true oder polymorphe Beziehungen werden nicht unterstützt.

Fazit

Virtuelle Felder sind ein mächtiges Feature in Payload CMS, mit dem Dokumente dynamisch angereichert werden können – ganz ohne redundante Datenhaltung oder aufgeblähte Schemata. Egal, ob vollständige Namen, Lesezeiten oder dynamische Labels: Sie helfen, das Content-Modell sauber, effizient und flexibel zu halten.

Danke fürs Lesen! Haben Sie einen spannenden Anwendungsfall für virtuelle Felder oder Fragen zur Integration in Ihrem Workflow? Wir freuen uns, von Ihnen zu hören! Für Feedback, Ideen oder Rückfragen erreichen Sie uns jederzeit unter info@jhb.software .