Um einen Gutenberg-Block für WordPress zu entwickeln, bereiten Sie eine Testumgebung vor und erstellen Sie ein Wireframe über @wordpress/create-block, beschreiben Sie die Einstellungen in block.json und die Bearbeitung implementieren in edit.js. Bei einem statischen Block wird das Markup im Beitragsinhalt gespeichert, während es bei einem dynamischen Block serverseitig generiert wird, beispielsweise durch render.php.

Inhalt

In diesem Leitfaden ermitteln Sie die passende Architektur, konfigurieren Blockattribute und untersuchen zwei Szenarien: eine Servicekarte und eine dynamische Beitragsliste. Die Entwicklung von Gutenberg-Blöcken sollte in einer Testumgebung mit Backup erfolgen: Vor der Bereitstellung sollten Sie separat die WordPress-Version, das aktive Theme, Plugins, Berechtigungen, Validierung und Datenmaskierung überprüfen.

Die Platzierung von Blöcken neben anderen Möglichkeiten zur Erweiterung des Geländes wird gezeigt in WordPress-Leitfaden für individuelle Entwicklung. Nachfolgend finden Sie die Schritte zum Erstellen Ihres eigenen Blocks.

Wenn Sie Ihren eigenen Block benötigen

Wenn Sie Ihren eigenen Editorblock benötigen

Ein benutzerdefinierter Block ist erforderlich, wenn die Standardfunktionen des Editors die Struktur, die Regeln oder die Logik der Inhaltsdarstellung nicht abdecken. Beispielsweise soll der Editor eine Servicekarte mithilfe einer Standardvorlage hinzufügen, anstatt sie jedes Mal manuell aus Titel, Bild, Text und Schaltfläche zusammenzustellen.

Die Entwicklung von Gutenberg-Blöcken ist dann sinnvoll, wenn die Lösung regelmäßig verwendet wird, ein einheitliches Design gewährleisten muss oder Daten von WordPress benötigt werden. Für eine einmalige Seite reichen in der Regel vorgefertigte Blöcke oder eine Vorlage aus.

Ein vorgefertigter Block, ein Muster oder ein neuer Block

Zunächst muss ermittelt werden, was genau dem Editor fehlt. Nicht jeder nicht standardmäßige Abschnitt erfordert Programmierung:

Fertiger Block Geeignet, wenn die Aufgabe mit Standard-Gutenberg-Werkzeugen gelöst werden kann, ohne die Struktur und das Design zu beeinträchtigen.
Muster Praktisch für die Wiederverwendung einer Komposition aus mehreren Blöcken. Es legt das anfängliche Layout fest, aber der Benutzer kann seine Elemente in der Regel unabhängig voneinander ändern.
Benutzerdefinierter Block Dies ist nützlich, wenn Sie die Anzahl der Felder einschränken, das Layout festlegen, spezielle Verhaltensweisen hinzufügen oder aktuelle Daten aus dem System abrufen möchten.

Bei Servicekarten hängt die Wahl von den Anforderungen ab. Benötigt der Redakteur feste Felder wie Titel, Beschreibung, Bild und Link, helfen die benutzerdefinierten Gutenberg-Blöcke, eine vorhersehbare Struktur zu gewährleisten. Handelt es sich bei der Karte hingegen lediglich um eine visuelle Vorlage, die freie Bearbeitung ermöglicht, ist es sinnvoller, mit einem Muster zu beginnen.

Alternativen bewerten. Zum Beispiel:, ACF in WordPress Geeignet für strukturierte Felder. Wählen Sie die Architektur entsprechend Ihrem Bearbeitungsszenario, den Plugin-Abhängigkeiten und den Kompetenzen Ihres Teams. Testen Sie die Kompatibilität mit Ihren WordPress-Versionen, Themes und Erweiterungen.

Statische und dynamische Ausgabe

Die zentrale architektonische Entscheidung betrifft den Zeitpunkt der Markup-Generierung: beim Speichern des Inhalts oder bei jedem Seitenaufruf. Dies bestimmt, wie der Block auf Datenänderungen reagiert und wie aufwendig die Wartung ist.

Kriterium	Statischer Block	Dynamischer Block
Ausgabe bilden	Die Formatierung wird zusammen mit dem Beitragsinhalt gespeichert.	Der Markup-Code wird auf dem Server erstellt, wenn die Seite angezeigt wird.
Wann zu verwenden	Inhalte können nur über den Blockeditor geändert werden.	Das Ergebnis hängt von den Aufzeichnungen, Einstellungen oder anderen relevanten Daten ab.
Ein geeignetes Szenario	Servicekarte mit manuell ausgefüllten Feldern	Liste der neuesten Beiträge in der ausgewählten Kategorie
Die größte Einschränkung	Bei einer Änderung der Struktur muss gegebenenfalls zuvor gespeichertes Markup berücksichtigt werden.	Das Ergebnis hängt von der Serverlogik ab und erfordert eine sorgfältige Datenprüfung.

Für eine Servicekarte ist ein statischer Ansatz in der Regel ausreichend, wenn alle Informationen vom Redakteur festgelegt werden und auf einer bestimmten Seite verbleiben sollen. Die dynamische Blockentwicklung mit WordPress Gutenberg eignet sich besser für eine Beitragsliste: Bei der Veröffentlichung neuer Inhalte kann eine solche Liste aktualisiert werden, ohne die Seite manuell bearbeiten zu müssen.

Vor der Auswahl sollten Sie die Datenquelle, die Aktualisierungsfrequenz und den akzeptablen Grad der Abhängigkeit von serverseitigem Code festlegen. Falls Benutzereingaben erforderlich sind, sollten Sie im Vorfeld Zugriffsrechte prüfen, Eingaben validieren und Ausgaben maskieren. Testen Sie die endgültige Lösung auf einer Testumgebung mit Backup, nicht direkt auf der Produktionsumgebung.

Bereiten Sie die Entwicklungsumgebung vor.

Vorbereitung der Umgebung und Testkopie für die Blockentwicklung

WordPress testen

Die Entwicklung von Gutenberg-Blöcken sollte in einer isolierten Umgebung und nicht auf einer Live-Website erfolgen. Sie können eine lokale WordPress-Installation oder eine Testumgebung Ihrer Website verwenden. Letztere ist hilfreich, wenn Sie die Interaktion des Blocks mit dem aktuellen Theme, den Plugins und den Servereinstellungen testen müssen.

Erstellen Sie vor Arbeitsbeginn eine Sicherungskopie Ihrer Dateien und Datenbank. Stellen Sie sicher, dass die Testumgebung keine Live-Bestellungen, Zahlungen oder Benutzeranfragen annimmt. Deaktivieren Sie für Ihren Shop Zahlungsbenachrichtigungen, Kunden-E-Mails und den CRM-Datenaustausch.

Es empfiehlt sich, die Versionen von WordPress, PHP, Theme und wichtigen Plugins in der Testumgebung so nah wie möglich an die Versionen der Live-Website anzugleichen. Eine konsistente Konfiguration allein garantiert keine Kompatibilität: Sie wird nach jedem größeren Update überprüft. Für die Diagnose werden Zugriff auf Fehlerprotokolle, Backups und PHP-Einstellungen benötigt.

Vor der Installation der Werkzeuge sollten die Ausgangsbedingungen dokumentiert werden:

WordPress-Version und aktives Theme;
PHP-Version und verfügbare Servererweiterungen;
Liste der Plugins, die den Editor und die Inhaltsausgabe beeinflussen;
Verfügbarkeit von HTTPS, Debug-Protokoll und Datensicherung;
Benutzerrollen, die berechtigt sind, einen Block hinzuzufügen und zu bearbeiten.

Zur Diagnose können Sie die WordPress-Fehlerprotokollierung auf Ihrer Testseite aktivieren. Vermeiden Sie es, Besuchern technische Meldungen anzuzeigen, und lassen Sie den Debug-Modus auf Ihrer Live-Website nicht aktiviert, da die Protokolle Dateipfade und andere Dienstinformationen offenlegen können.

Montagewerkzeuge

Moderne, benutzerdefinierte Gutenberg-Blöcke verwenden typischerweise JavaScript, JSX und WordPress-Pakete. Daher benötigen Sie Node.js und npm. Wählen Sie eine unterstützte Version von Node.js und prüfen Sie, ob diese mit den Anforderungen der verwendeten Pakete kompatibel ist, anstatt eine veraltete Version zu installieren.

Offizielles Paket @wordpress/create-block Hilft bei der Vorbereitung der Plugin-Struktur und der Konfiguration des Build-Systems. Vor der Ausführung sollte Node.js mit dem Befehl überprüft werden. node --version, und npm - mit dem Befehl npm --version. Der Generator selbst kann aufgerufen werden durch npx @wordpress/create-block; Die Projektparameter legen Sie im nächsten Schritt fest.

Bereiten Sie außerdem einen Code-Editor, ein Terminal, Git und die Entwicklertools Ihres Browsers vor. Mit Git können Sie Blockänderungen von anderen Entwicklungen trennen und zu einem stabilen Zustand zurückkehren. Fügen Sie dem Repository keine Passwörter, API-Schlüssel, Datenbank-Backups oder Konfigurationsdateien mit vertraulichen Informationen hinzu.

Wenn Ihr Team mit unterschiedlichen Betriebssystemen arbeitet, dokumentieren Sie die Versionen von Node.js, des Paketmanagers und des Ausführungsbefehls in der Projektdokumentation. Dadurch wird das Risiko verringert, dass ein Build zwar für einen Entwickler funktioniert, aber für einen anderen nicht reproduzierbar ist. Installieren Sie vor dem Deployment auf der Produktionsumgebung die Abhängigkeiten und führen Sie den Build nur in einer kontrollierten Umgebung durch. Testen Sie die Ergebnisse anschließend in der Staging-Umgebung.

Erstelle eine Blockbasis

Der Benutzerblock besteht aus: Metadaten, Editor und Ausgabe

block.json-Metadaten

Es ist bequemer, die Grundlage des Blocks in einer Datei zu beschreiben. block.json. WordPress nutzt es als zentrale Metadatenquelle: Blockname, Kategorie, eingebundene Skripte und Stile, unterstützte Funktionen und Datenstruktur. Ein Projekt, das erstellt wurde durch @wordpress/create-block, enthält bereits eine solche Datei und einen Basisregistrierungspunkt.

Im Szenario «Servicekarte» könnte die minimale Konfiguration folgendermaßen aussehen:

{ "$schema": "https://schemas.wp.org/trunk/block.json", "apiVersion": 3, "name": "project/service-card", "version": "0.1.0", "title": "Servicekarte", "category": "widgets", "icon": "index-card", "description": "Karte mit Titel, Beschreibung und Link", "supports": { "html": false }, "attributes": { "title": { "type": "string", "default": "" }, "description": { "type": "string", "default": "" }, "url": { "type": "string", "default": "" } }, "editorScript": "file:./index.js", "editorStyle": "file:./index.css", "style": "file:./style-index.css" }

Feld Name muss einen Namensraum und einen eindeutigen Namen enthalten, zum Beispiel Projekt-/Servicekarte. Nach der Veröffentlichung eines Blocks ist es nicht ratsam, diesen ohne vorherige Migration zu ändern: WordPress verwendet diesen Namen, um gespeichertes Markup zu erkennen.

Editor-Skript zeigt auf den JavaScript-Editor., Editor-Stil — nur für Stile im administrativen Bereich, und Stil — für allgemeine Blockstile. Überprüfen Sie nach dem Build die Dateiverbindungen, die WordPress-Version und die Infrastrukturbeschränkungen.

Redaktioneller Teil und Attribute

Datei edit.js ist für die Benutzeroberfläche verantwortlich, die Sie in Gutenberg sehen. Daten sollten in Blockattributen gespeichert werden, wenn sie mit der Publikation gespeichert werden sollen. setAttributes Diese Werte werden während der Eingabe aktualisiert.

import { useBlockProps, RichText } from &#039;@wordpress/block-editor&#039;; export default function Edit({ attributes, setAttributes }) { const { title, description } = attributes; return (
    <div {...useblockprops()}>
      <richtext
        tagname="h3"
        value="{title}"
        placeholder="Название услуги"
        onchange="{(value)" > setAttributes({ title: value })} /&gt;
      <richtext
        tagname="p"
        value="{description}"
        placeholder="Краткое описание"
        onchange="{(value)" > setAttributes({ description: value })} /&gt;
    </div>
  );
}

useBlockProps() Fügt die erforderlichen Wrapper-Eigenschaften hinzu, die es dem Editor ermöglichen, den Block auszuwählen, zu verschieben und anzupassen. Die Komponente RichText Geeignet für formatierten Text. Für URLs, Zahlen oder Optionsfelder empfiehlt es sich, spezielle Steuerelemente zu verwenden und die zulässigen Werte separat einzuschränken.

Attributtyp in block.json Beschreibt das Datenformat, ersetzt aber nicht die Validierung und sichere Ausgabe. URLs müssen geprüft, Texte kontextabhängig maskiert und Benutzerberechtigungen für Operationen mit sensiblen Daten überprüft werden. Bei einem statischen Block werden Attribute in speicherbares Markup umgewandelt und können bei der Entwicklung dynamischer Blöcke mit Gutenberg an den Server-Handler übergeben werden. Bevor Sie Ihr Plugin aktivieren, erstellen Sie eine Testumgebung und ein Backup Ihrer Website: Die Kompatibilität mit Theme, Plugins und der installierten WordPress-Version muss separat getestet werden.

Ausgabe und Daten anpassen

Blockdaten aus den Editoreinstellungen in die Anzeige übertragen

Wählen Sie die Ausgabemethode anhand der Datenquelle. Wenn sich der Inhalt nur beim Bearbeiten eines Blocks ändert, speichern Sie das fertige Markup im Beitrag. Wenn das Ergebnis von aktuellen Beiträgen, Einstellungen oder dem Status der Website abhängt, generieren Sie das HTML bei jeder Anfrage serverseitig.

Option	Wann zu verwenden	Einschränkungen
Statischer Block	Servicekarte, Warnung, formatierter Text mit Bild	Eine Änderung der gespeicherten Struktur kann die Migration der alten Inhalte erforderlich machen.
Dynamischer Block	Liste der Datensätze, Daten aus den Einstellungen oder Abfrageergebnisse	Die Ausgabe hängt vom PHP-Code ab und verursacht beim Generieren der Seite eine Serverlast.

Statische Lagerung

Definieren Sie für die Servicekarte die Blockattribute in block.json: Zum Beispiel, Titel, Beschreibung Und URL. IN edit.js Man erhält sie durch Attribute, und Sie übertragen die Änderungen durch setAttributes. Prüfen Sie den Typ jedes Wertes: Eine Zeichenkette sollte nicht unerwartet in ein Array oder einen booleschen Wert umgewandelt werden.

Funktion speichern Gibt das Markup zurück, das in den Seiteninhalt geschrieben wird. Es sollte ausschließlich von Blockattributen und eingebetteten Inhalten abhängen, nicht von einer externen API oder dem aktuellen Datum. Andernfalls entspricht das gespeicherte Markup nicht mehr dem erwarteten Schema.

Wenn Sie den HTML-Code eines bereits veröffentlichten Blocks ändern, kann WordPress diesen ungültig machen. Vermeiden Sie daher Änderungen an Klassen und Struktur, es sei denn, diese sind unbedingt erforderlich. Stellen Sie für eine neue, inkompatible Version ein Legacy-Blockschema mit Attributtransformationen bereit oder erstellen Sie eine separate Version. Überprüfen Sie auch bereits erstellte Seiten.

Dynamisches Rendering

Für eine dynamische Liste von Datensätzen geben Sie Folgendes an: block.json Rendering-Datei, zum Beispiel ""render": "file:./render.php"". Der Editor speichert die Blockeinstellungen – die Anzahl der Elemente, die ausgewählte Kategorie und Reihenfolge – und render.php empfängt Attribute und generiert auf dem Server den eigentlichen HTML-Code.

In der dynamischen Blockfunktion speichern kehrt normalerweise zurück null, wenn Sie die Sicherungsmarkierung nicht speichern müssen. In render.php Normalisieren Sie die Eingabeparameter vor der Abfrage: Konvertieren Sie die Anzahl der Datensätze in eine ganze Zahl und begrenzen Sie sie auf einen zulässigen Bereich, prüfen Sie, ob die Kategorie-ID eine positive Zahl ist, und wählen Sie die Sortierrichtung nur aus einer vordefinierten Liste aus.

Bei der Ausgabe müssen die Daten kontextabhängig maskiert werden: Text - durch esc_html(), URL - via esc_url(), HTML-Attributwerte - bis esc_attr(). Wenn eine Blockierung auf eingeschränkte Inhalte zugreift oder administrative Aktionen erfordert, prüfen Sie Benutzerberechtigungen und Nonce separat. Übergeben Sie Blockparameter nicht direkt an SQL oder HTML.

Die Editor-Vorschau kann aufgrund von Theme-Stilen und aktivierten Plugins vom Frontend abweichen. Geben Sie daher keine Kompatibilitätsgarantie: Testen Sie beide Bereiche auf einer Testumgebung mit derselben WordPress-Version, demselben Theme und denselben Erweiterungen wie auf Ihrer Live-Website. Sichern Sie Ihre Datenbank und Dateien, bevor Sie einen bestehenden Block ersetzen.

Prüfen Sie den Block vor der Implementierung.

Testen Sie den Block vor der Veröffentlichung auf einer Testumgebung Ihrer Website und erstellen Sie ein Backup. Die Tests sollten nicht nur das Erscheinungsbild, sondern auch die Beibehaltung der Blockattribute, Zugriffsrechte, den Umgang mit ungültigen Daten und das Verhalten nach einem Seitenneuladen umfassen. Ohne Tests mit der spezifischen WordPress-Version, dem aktiven Theme und den installierten Plugins kann die Kompatibilität nicht gewährleistet werden.

Editor und Frontend

Fügen Sie zunächst den Block im Gutenberg-Editor hinzu und füllen Sie alle verfügbaren Felder aus. Achten Sie darauf, dass die Steuerelemente übersichtlich sind, Änderungen sofort im Bearbeitungsbereich sichtbar sind und die eingegebenen Werte nach dem Aktualisieren des Beitrags gespeichert werden. Prüfen Sie, ob Felder leer sind, der Titel zu lang ist, Sonderzeichen verwendet werden, Bilder unterschiedliche Seitenverhältnisse aufweisen oder mehrere Blockinstanzen mehrfach hinzugefügt wurden.

Vergleichen Sie die Editoransicht mit der veröffentlichten Seite. Bei einem statischen Block ist es wichtig, dass das gespeicherte Markup mit der aktuellen Implementierung übereinstimmt. Überprüfen Sie bei einem dynamischen Block das serverseitig generierte Ergebnis. render.phpDie Ausgabe darf keine privaten Aufzeichnungen oder Daten offenlegen, auf die der aktuelle Benutzer keinen Zugriff hat.

Alle Daten müssen vor dem Speichern validiert und bei der Ausgabe maskiert werden. Verwenden Sie für Text die entsprechenden WordPress-Funktionen anstelle einer generischen Standardverarbeitung: Klartext, URLs und gültiges HTML erfordern unterschiedliche Maskierungsmethoden. Wenn ein Block eine geschützte Aktion ausführt, überprüfen Sie die Benutzerberechtigungen und die Nonce. Das bloße Vorhandensein eines Blocks im Editor sollte keine zusätzlichen Berechtigungen gewähren.

Verwenden Sie die folgende Checkliste:

Der Block kann hinzugefügt, angepasst, verschoben, dupliziert und gelöscht werden;
Blockattribute bleiben ohne Verlust oder unerwartete Datentransformation erhalten;
Der leere Zustand enthält einen klaren Hinweis und führt nicht zu einem Seitenumbruch;
Das Markup ist im Editor, in der Vorschau und im Frontend korrekt;
Dynamische Abfragen sind auf die benötigten Daten beschränkt und berücksichtigen den Veröffentlichungsstatus;
Validierung, Escape-Sequenzen, Zugriffsrechte und Fehlerbehandlung wurden geprüft;
Es gibt keine blockbezogenen Fehler oder Warnungen in der Browserkonsole oder im PHP-Log;
Blockstile verändern keine fremden Elemente der Website.

Mobile-Bildschirm und Updates

Testen Sie den Block auf schmalen, mittleren und breiten Bildschirmen. Die Servicekarte sollte übersichtlich bleiben, und Schaltflächen sollten nicht über die Grenzen des Containers hinausragen. Prüfen Sie bei einer dynamischen Liste von Einträgen den Zeilenumbruch langer Überschriften, die Bildgrößen und das Verhalten, wenn keine Ergebnisse gefunden werden. Der responsive Anzeigemodus allein reicht nicht aus: Öffnen Sie die Seite nach Möglichkeit auf einem echten Mobilgerät und testen Sie die Touch-Steuerung.

Testen Sie anschließend die Aktualisierung des Blocks selbst. Änderungen an der Attributstruktur oder am gespeicherten Markup können zuvor hinzugefügte Instanzen ungültig machen. Öffnen Sie ältere Beiträge in der Staging-Umgebung und testen Sie diese im Editor und auf der Website. Berücksichtigen Sie bei Änderungen am statischen Markup ältere Blockversionen und die Datenmigration; dynamische Ausgaben werden in der Regel zentral aktualisiert, erfordern aber ebenfalls eine Validierung von Vorlagen und Abfragen.

Wiederholen Sie die Tests nach jedem Update von WordPress, Ihrem Theme oder abhängigen Plugins. Stellen Sie den Block erst dann auf Ihrer Live-Website bereit, nachdem Sie eine Sicherungskopie erstellt und einen schnellen Wiederherstellungsplan parat haben.

Offizielle Dokumentation: Leitfaden zur Blockerstellung.