Seiten mit Blöcken erstellen

Auf dieser Seite

Ein blocks-Feld speichert eine geordnete Seitenkomposition. Jedes Element hält einen Blocktyp, eine beibehaltene Schema-Version, einen stabilen Schlüssel und die von dieser Version deklarierten Felder fest. Redakteure fügen Blöcke im Inhaltseditor hinzu und ordnen sie neu an. Die Astro-Route ordnet jeden Blocktyp einer Komponente zu.

Blocktypen definieren

Definieren Sie Blocktypen vor dem Collection-Feld, das sie verwendet. Ein Seed bewahrt jede nummerierte Version und den aktiven currentVersion-Zeiger.

Der folgende Seed definiert die Blöcke Hero und Feature grid und macht sie dann in einem layout-Feld der Pages-Collection verfügbar:

{
  "$schema": "https://emdashcms.com/seed.schema.json",
  "version": "1",
  "blockTypes": [
    {
      "slug": "hero",
      "label": "Hero",
      "description": "A heading, body text and an image",
      "icon": "sparkle",
      "category": "Layout",
      "currentVersion": 1,
      "versions": [
        {
          "version": 1,
          "fields": [
            { "slug": "heading", "label": "Heading", "type": "string", "required": true },
            { "slug": "body", "label": "Body", "type": "portableText" },
            { "slug": "image", "label": "Image", "type": "image" },
            { "slug": "link_label", "label": "Link label", "type": "string" },
            { "slug": "link_url", "label": "Link URL", "type": "url" }
          ]
        }
      ]
    },
    {
      "slug": "feature_grid",
      "label": "Feature grid",
      "description": "A heading and a grid of features",
      "icon": "squares-four",
      "category": "Layout",
      "currentVersion": 1,
      "versions": [
        {
          "version": 1,
          "fields": [
            { "slug": "heading", "label": "Heading", "type": "string" },
            {
              "slug": "items",
              "label": "Items",
              "type": "repeater",
              "validation": {
                "subFields": [
                  { "slug": "title", "label": "Title", "type": "string", "required": true },
                  { "slug": "description", "label": "Description", "type": "text" }
                ]
              }
            }
          ]
        }
      ]
    }
  ],
  "collections": [
    {
      "slug": "pages",
      "label": "Pages",
      "fields": [
        { "slug": "title", "label": "Title", "type": "string", "required": true },
        {
          "slug": "layout",
          "label": "Layout",
          "type": "blocks",
          "validation": {
            "allowedTypes": ["hero", "feature_grid"],
            "maxItems": 20
          }
        }
      ]
    }
  ]
}

Die Blockauswahl listet die Blocktypen in der Reihenfolge von allowedTypes auf, gruppiert nach category, und zeigt für jeden Typ description und icon an. Setzen Sie icon auf den Namen eines Phosphor-Icons, etwa sparkle oder chart-bar; Redakteure sehen es auch an jedem Block im Inhaltseditor. Ein Blocktyp ohne Icon oder mit einem Namen, der keinem Phosphor-Icon entspricht, zeigt ein allgemeines Block-Icon.

Entfernen Sie später einen erlaubten Typ, verschiebt EmDash ihn in die servergesteuerte Liste retiredTypes. Vorhandene Blöcke bleiben bearbeitbar, aber Redakteure können diesen Typ nicht mehr hinzufügen oder duplizieren.

Felder für das Editor-Layout benennen

Ein geöffneter Block im Inhaltseditor zeigt zuerst seinen Inhalt: Text, Rich Text, Fotos und Listen, jeweils unter ihrer Beschriftung. Danach folgen die Einstellungen als Zeilen mit der Beschriftung neben dem Wert und schließlich eine Advanced-Zeile. Der Editor platziert jedes Feld anhand seines Typs und Slugs, nicht anhand seiner Beschriftung, und zeigt jede Beschriftung so an, wie sie geschrieben ist. Diese Konventionen ändern, wohin ein Feld kommt:

  • Link-Felder. Ein url-Feld oder ein string-Feld, dessen Slug auf _url, _link oder _href endet, erhält eine Einstellungszeile.
  • Buttons. Ein string-Feld namens {base}_label, {base}_text oder {base} teilt sich eine Zeile mit einem Link-Feld namens {base}_url, {base}_link oder {base}_href. Die Zeile übernimmt die Beschriftung des Textfelds. Im Hero oben teilen sich link_label und link_url eine Zeile mit der Beschriftung „Link label“.
  • Bildunterschriften. Ein string-Feld namens {image}_caption steht unter dem image-Feld namens {image}, etwa photo_caption unter photo.
  • Abschnitts-ID. Ein Feld namens anchor_id kommt in die Advanced-Zeile.
  • Überschrift. Das erste string- oder text-Feld, dessen Slug das Wort headline, heading, title oder statement enthält, wird größer als Überschrift des Blocks dargestellt. Ein Feld, dessen Slug das Wort label, eyebrow, kicker oder tag enthält, ist nie die Überschrift. Slugs werden an Unterstrichen in Wörter zerlegt, daher zählt section_heading, subheadline aber nicht. Passt kein Feld, ist das erste string- oder text-Feld des Blocks die Überschrift, es sei denn, sein Slug enthält eines dieser ausgeschlossenen Wörter.

Ein repeater-Feld in einem Block erhält seine Form aus seinen Unterfeldern:

  • Eingabeliste. Eine Liste mit genau einem Unterfeld vom Typ string oder url zeigt jeden Eintrag als Zeile mit Aufzählungspunkt. Mit Enter fügen Sie eine Zeile hinzu, und beim Einfügen mehrerer Zeilen entsteht pro Zeile ein Eintrag. Eine Liste von Kundennamen passt zu dieser Form.
  • Tabelle. Eine Liste mit bis zu drei Unterfeldern, jeweils vom Typ string, url, number, integer, select oder image, und höchstens einem image, zeigt pro Eintrag eine Zeile und pro Unterfeld eine Spalte. Eine Liste von Kennzahlen mit Wert und Beschriftung passt zu dieser Form.
  • Aufklappbare Einträge. Jede andere Liste zeigt jeden Eintrag als Zeile, die sich zum Bearbeiten seiner Unterfelder öffnet. Ein geöffneter Eintrag ordnet seine Unterfelder nach den obigen Regeln an, außer dass kein Unterfeld als Überschrift dargestellt wird oder in eine Advanced-Zeile kommt, ein Foto eine Einstellungszeile erhält und {image}_caption ein gewöhnliches Textfeld ist.

Der Titel eines Eintrags ist sein erstes string-Unterfeld, das weder ein Link-Feld noch der Text eines Buttons ist, andernfalls sein erstes text-Unterfeld. Ein geschlossener Eintrag zeigt seinen Titel, gefolgt von bis zu zwei seiner anderen string-Werte. Sind diese alle leer, zeigt er stattdessen den Anfang seines ersten anderen text-Werts. Im Feature grid oben erscheint items als aufklappbare Einträge, die nach title benannt sind. Fügen Sie dem Blocktyp einer Tabelle ein viertes Unterfeld oder ein text-Unterfeld hinzu, wird die Liste zu aufklappbaren Einträgen.

Diese Regeln sind Layout-Hinweise nach bestem Bemühen und können sich in einer späteren Version ändern. Sie betreffen nur, wie der Editor das Formular anordnet, und ein Feld, das auf keine davon passt, erhält eine eigene Zeile.

Die Astro-Komponenten erstellen

Jede Komponente erhält value, index und blockKey. Der Wert enthält _type, _version und _key, sodass eine Komponente beibehaltene Versionen eingrenzen kann, wenn sich ihr Block-Schema weiterentwickelt.

Die Hero-Komponente liest jeden angezeigten Wert aus dem gespeicherten Block:

---
import { sanitizeHref } from "emdash";
import { Image, PortableText, type BlockComponentProps } from "emdash/ui";
import type { PageLayoutBlock } from "../../../emdash-env";

type HeroBlock = Extract<PageLayoutBlock, { _type: "hero" }>;
type Props = BlockComponentProps<HeroBlock>;

const { value } = Astro.props;
---

<section class="hero">
  <div>
    <h1>{value.heading}</h1>
    {value.body && <PortableText value={value.body} />}
    {value.link_url && <a href={sanitizeHref(value.link_url)}>{value.link_label}</a>}
  </div>
  {value.image && <Image image={value.image} />}
</section>

Erstellen Sie für jeden erlaubten Typ eine Komponente. Die Komponente steuert Markup und Styling; der Blockwert liefert Inhalt und Medien.

Die Komposition rendern

Verwenden Sie defineBlockComponents, um für jeden _type in der generierten Feld-Union genau eine Komponente zu verlangen. Übergeben Sie diese Zuordnung in der Seitenroute an <Blocks>.

---
import { decodeSlug, getEmDashEntry } from "emdash";
import { Blocks, defineBlockComponents } from "emdash/ui";
import type { PageLayoutBlock } from "../../../emdash-env";
import FeatureGrid from "../../components/blocks/FeatureGrid.astro";
import Hero from "../../components/blocks/Hero.astro";

const slug = decodeSlug(Astro.params.slug);
if (!slug) return Astro.rewrite("/404");

const { entry: page, cacheHint } = await getEmDashEntry("pages", slug);
if (!page) return Astro.rewrite("/404");
Astro.cache.set(cacheHint);

const components = defineBlockComponents<PageLayoutBlock>({
  hero: Hero,
  feature_grid: FeatureGrid,
});
---

<Blocks value={page.data.layout} components={components} />

<Blocks> führt keine Inhalts-, Schema-, Medien- oder Netzwerkabfragen aus. Es rendert das übergebene Array in der gespeicherten Reihenfolge. Eine Blockkomponente kann eine explizite Anwendungsabfrage ausführen, wenn sie weitere Daten benötigt.

Mit einer fehlenden Komponente umgehen

Während der Entwicklung erzeugt ein nicht zugeordneter Typ einen sichtbaren Platzhalter und eine Konsolenwarnung. Der Platzhalter nennt den _type, gibt den gespeicherten Blockwert aber nicht aus.

In der Produktion rendert ein nicht zugeordneter Typ die fallback-Komponente, sofern angegeben. Andernfalls erzeugt er keine Ausgabe:

---
import MissingBlock from "../../components/blocks/MissingBlock.astro";
---

<Blocks value={page.data.layout} components={components} fallback={MissingBlock} />

Liefern Sie die Renderer-Unterstützung aus, bevor Sie einen Blocktyp aktivieren, der von Produktionsinhalten verwendet wird.

Ein Block-Schema ändern

Kompatible Änderungen ergänzen die aktive Version. Das Hinzufügen eines optionalen Felds, das Hinzufügen eines Standardwerts oder das Lockern der Validierung behält dieselbe Versionsnummer bei. Gespeicherte Blöcke erhalten die Standardwerte beim nächsten Schreiben.

Eine inkompatible Änderung erzeugt eine inaktive Version. Das Entfernen eines Felds, das Ändern eines Feldtyps, das Hinzufügen eines Pflichtfelds oder das Verschärfen der Validierung ist inkompatibel.

  1. Erstellen Sie die inkompatible Version über die Schema-API oder MCP. Lassen Sie sie inaktiv.

  2. Aktualisieren Sie den Renderer so, dass er sowohl die beibehaltene als auch die neue Version verarbeitet. Stellen Sie den Renderer bereit.

  3. Aktivieren Sie die neue Version. Neue Blöcke verwenden sie nach der Aktivierung.

  4. Migrieren Sie gespeicherte Blöcke explizit mit migrateBlocks: true. Behalten Sie dabei jeden Block-_key bei, während Sie _version und die versionsspezifischen Felder ändern.

Alte Versionen bleiben für Revisionen, Entwürfe, Medien-Tracking und gespeicherte Inhalte verfügbar. Für Blocktypen und beibehaltene Versionen gibt es keine endgültige Löschoperation.

Unterstützte verschachtelte Felder

Block-Definitionen unterstützen string, text, url, number, integer, boolean, datetime, select, multiSelect, portableText, image, file und repeater.

Referenzen, JSON, Slugs, verschachtelte Blöcke, benutzerdefinierte Widgets, physische Indizes, Eindeutigkeit und Lokalisierung pro Unterfeld werden innerhalb einer Block-Definition nicht unterstützt. Ein blocks-Feld selbst kann nicht erforderlich, eindeutig, durchsuchbar, indiziert sein und erhält auch kein benutzerdefiniertes Feld-Widget.

Die genauen Regeln für die Feldvalidierung und gespeicherte Werte finden Sie in der Referenz zum blocks-Feld. Zu Seed-Konflikten und Exportverhalten siehe Seed-Dateien.