Erstellen benutzerdefinierter Gutenberg-Blöcke: Das definitive Blockentwicklungs-Tutorial

Viele Menschen beschweren sich über die Hürden beim Einstieg in die Erstellung von Gutenberg-Blöcken und -Apps. Die Lernkurve ist steil, hauptsächlich aufgrund der Schwierigkeit, die Entwicklungsumgebung zu installieren und zu konfigurieren. Darüber hinaus sind solide Kenntnisse in JavaScript, Node.js, React und Redux unverzichtbare Zutaten für dieses ziemlich komplexe Rezept.

Das offizielle WordPress-Blockeditor-Handbuch bietet Entwicklern eine enorme Menge an Informationen, aber Sie könnten sich in diesem Meer von Details verlieren.

Und es ist erwähnenswert, was Matias Ventura, leitender Architekt des Gutenberg-Projekts, in seinem Interview mit WP Tavern berichtete:

Während es Leute gibt, die es schnell lernen können, ist es immer noch eine große Hürde für die Menschen. Ich denke, das hat mehrere Ebenen; Die Dokumentation könnte sowohl in der Organisation als auch in der Präsentation um eine Größenordnung besser sein. Ich hoffe, wir können da noch viel machen.

Vor diesem Hintergrund haben wir uns entschieden, ein Schritt-für-Schritt-Tutorial bereitzustellen, das unseren Lesern den Einstieg in die Entwicklung von Gutenberg-Blöcken erleichtern soll.

Hört sich interessant an? Tauchen wir ein!

Voraussetzungen für die Entwicklung des Gutenberg-Blocks

Die einzigen erforderlichen Fähigkeiten für dieses Tutorial sind gute Kenntnisse der Entwicklung von WordPress-Plugins und mindestens ein grundlegendes Verständnis von HTML, CSS, JavaScript und React.

Wird das ein ambitioniertes Projekt? Sie wetten, es wird!

Es war nicht einfach, den richtigen Kompromiss zwischen Vollständigkeit und Einfachheit zu finden oder zu entscheiden, welche Themen aufgenommen und welche weggelassen werden sollten.

Hoffentlich werden uns fortgeschrittene und fortgeschrittene Leser verzeihen, dass wir uns nicht tief in bestimmte Konzepte wie React-Zustand, Redux-Speicher, High-Order-Komponenten und so weiter vertieft haben. Diese Themen erfordern zusätzlichen Raum und Aufmerksamkeit und sind wahrscheinlich zu fortgeschritten, um mit der Blockentwicklung zu beginnen (es sei denn, Sie sind ein React-Entwickler).

Aus dem gleichen Grund werden wir einige der fortgeschritteneren Themen im Zusammenhang mit der Entwicklung von Gutenberg-Blöcken, wie dynamische Blöcke und Metaboxen, nicht behandeln.

Mit dem Wissen, das Sie am Ende dieses Artikels erwerben, können Sie sofort Spaß haben und produktiv sein.

Sobald Sie mit dem Blockbau beginnen, sind Sie bereit, Ihre Fähigkeiten weiter zu verbessern und selbst noch fortgeschrittenere Gutenberg-Blöcke zu bauen.

Was ist ein Gutenberg-Block?

Seit seiner ersten Veröffentlichung im Dezember 2018 wurde der Blockeditor in allen Aspekten stark verbessert: leistungsfähigere APIs, eine fortschrittlichere Benutzeroberfläche, verbesserte Benutzerfreundlichkeit, eine Menge neuer Blöcke, die ersten Implementierungen von Full Site Editing und vieles mehr .

Kurz gesagt, auch wenn sich Gutenberg noch in starker Entwicklung befindet, hat es einen langen Weg zurückgelegt – und heute ist der Blockeditor ein vollwertiger Kandidat als zuverlässiger, funktionaler Seiten- und Site-Builder.

Aus der Sicht eines Entwicklers ist Gutenberg eine React-basierte Single Page Application (SPA), die es WordPress-Benutzern ermöglicht, Inhalte in WordPress zu erstellen, zu bearbeiten und zu löschen. Dies sollte Sie jedoch nicht an eine erweiterte Version des traditionellen Inhaltseditors denken lassen.

Das wollen wir deutlich machen:

In Gutenberg ist der Inhalt in Blöcke unterteilt, die „Bausteine“ sind, mit denen Benutzer Beiträge und Seiten oder ihre gesamten Websites erstellen können.

Aber was ist technisch gesehen ein Block?

Wir mögen die Definition von WordPress:

„Block“ ist der abstrakte Begriff, der verwendet wird, um Markup-Einheiten zu beschreiben, die zusammengesetzt den Inhalt oder das Layout einer Webseite bilden. Die Idee kombiniert Konzepte dessen, was wir heute in WordPress mit Shortcodes, benutzerdefiniertem HTML und eingebetteter Entdeckung in einer einzigen konsistenten API und Benutzererfahrung erreichen.

Titel, Absätze, Spalten, Bilder, Galerien und alle Elemente, aus denen die Benutzeroberfläche des Editors besteht, von Seitenleisten bis hin zu Blocksymbolleisten-Steuerelementen, sind React-Komponenten.

Also, was sind React-Komponenten? W3Schools bietet die folgende Definition:

Komponenten sind unabhängige und wiederverwendbare Codebits. Sie dienen demselben Zweck wie JavaScript-Funktionen, arbeiten jedoch isoliert und geben HTML über eine render() Funktion zurück.

Während das von Gutenberg bereitgestellte Bearbeitungserlebnis im Vergleich zum klassischen WordPress-Editor neu ist, ändert sich die Art und Weise, wie WordPress Ihre Inhalte in der Datenbank speichert, überhaupt nicht. Das liegt daran, dass Gutenberg eine Anwendung ist, die innerhalb von WordPress funktioniert, aber die Funktionsweise des CMS im Kern nicht ändert.

Beiträge (und dazu gehören Beiträge, Seiten und benutzerdefinierte Beitragstypen), die mit Gutenberg erstellt wurden, werden weiterhin in der Tabelle wp_posts gespeichert, genau wie beim klassischen Editor.

Aber in einem mit Gutenberg erstellten Beitrag finden Sie zusätzliche Informationen in der Tabelle, die einen grundlegenden Unterschied zwischen Beiträgen darstellen, die mit dem klassischen Editor erstellt wurden, und Gutenberg.

Diese Informationen sehen aus wie HTML-Kommentare und haben eine bestimmte Funktion: Blöcke begrenzen:

Blocktrennzeichen teilen WordPress mit, welcher Block auf dem Bildschirm gerendert werden soll. Sie stellen auch Werte für Blockeigenschaften in einem JSON-Objekt bereit. Diese Requisiten bestimmen, wie der Block auf dem Bildschirm gerendert werden soll:

Einrichten Ihrer WordPress-Entwicklungsumgebung

Die Einrichtung einer modernen JavaScript-Entwicklungsumgebung erfordert solide Kenntnisse fortschrittlicher Technologien wie Webpack, React und JSX, Babel, ESLint usw.

Eingeschüchtert? Sei nicht! Die WordPress-Community ist bereits zur Rettung gekommen, indem sie leistungsstarke Tools bereitstellt, mit denen Sie einen unordentlichen manuellen Konfigurationsprozess vermeiden können.

Der Einfachheit halber gehen wir in diesem Artikel nicht auf das Transpilieren ein (mit dem wir Ihnen dennoch empfehlen, sich damit vertraut zu machen, sobald Sie die Grundlagen der Blockentwicklung erlernt haben). Stattdessen stellen wir zwei alternative Tools vor, mit denen Sie in wenigen Minuten schnell und einfach eine moderne JavaScript-Entwicklungsumgebung einrichten können. Es liegt an Ihnen, diejenige auszuwählen, die Sie für Ihr Projekt am bequemsten finden.

Das Einrichten einer JavaScript-Entwicklungsumgebung zum Erstellen von Gutenberg-Blöcken ist ein dreistufiger Prozess:

1. Installieren Sie Node.js und npm
2. Richten Sie die Entwicklungsumgebung ein
3. Richten Sie das Block-Plugin ein

Lass uns anfangen.

1. Installieren Sie Node.js und npm

Bevor Sie Ihre Entwicklungsumgebung installieren und Ihren ersten Block registrieren, müssen Sie Node.js und den Node-Paketmanager (npm) installieren.

Sie können Node.js und npm auf verschiedene Arten installieren. Zunächst sollten Sie jedoch überprüfen, ob die Software bereits auf Ihrem Computer installiert ist.

Starten Sie dazu das Terminal und führen Sie den folgenden Befehl aus:

 node -v

Wenn das Ergebnis command not found lautet, ist Node.js nicht auf Ihrem Computer installiert und Sie können mit der Installation fortfahren.

Für diesen Artikel haben wir die einfachste Installationsoption ausgewählt, nämlich den Node Installer. Sie müssen lediglich die Ihrem Betriebssystem entsprechende Version herunterladen und den Installationsassistenten starten:

Führen Sie nach der Installation von Node.js den Befehl node -v erneut in Ihrem Terminal aus. Sie können auch den Befehl npm -v ausführen, um zu bestätigen, dass das npm-Paket verfügbar ist.

Sie sind jetzt mit den folgenden Tools ausgestattet:

• Der Paket-Runner npx Node.js (siehe Dokumentation). Auf diese Weise können Sie einen npm -Befehl ausführen, ohne ihn zuerst zu installieren.
• Der npm Node.js-Paketmanager (siehe Dokumentation). Dies wird verwendet, um Abhängigkeiten zu installieren und Skripts auszuführen.

Der nächste Schritt ist die Installation der Entwicklungsumgebung.

2. Richten Sie Ihre Entwicklungsumgebung ein

Sobald Sie die neuesten Versionen von Node.js und npm auf Ihrem lokalen Computer haben, benötigen Sie eine Entwicklungsumgebung für WordPress.

Sie können entweder eine lokale Entwicklungsumgebung wie DevKinsta verwenden oder das offizielle WordPress-Tool verwenden. Werfen wir einen Blick auf beide Optionen.

Option 1: Lokale Entwicklungsumgebung (DevKinsta)

Mit nur wenigen Klicks kannst du WordPress lokal mit DevKinsta, unserem modernen lokalen WordPress-Entwicklungstool, installieren. Oder Sie entscheiden sich für ein anderes lokales Entwicklungstool wie MAMP oder XAMPP:

Option 2: wp-env

Sie können sich auch für das offizielle wp-env Tool entscheiden, das eine lokale WordPress-Entwicklungsumgebung bietet, die Sie direkt von der Befehlszeile aus starten können. Noah Alen definiert es wie folgt:

Lokale WordPress-Umgebungen sind jetzt so einfach wie das Ausführen eines einzigen Befehls. wp-env ist ein Zero-Config-Tool für schmerzlose lokale WordPress-Umgebungen. Es bietet Entscheidungen über Optionen, sodass Benutzer WordPress schnell hochfahren können, ohne Zeit zu verschwenden. Das Ziel besteht in der Tat darin, diese Umgebungen für alle leicht zugänglich zu machen – egal, ob Sie Entwickler, Designer, Manager oder sonst jemand sind.

Wenn Sie sich entscheiden, es auszuprobieren, erfordert die Installation von wp-env nur minimalen Aufwand. Folgen Sie einfach diesen Schritten:

Schritt 1: Bestätigen Sie die Installation von Docker und Node.js

Um die technischen Anforderungen zu erfüllen, müssen Sie zunächst sowohl Docker als auch Node.js auf Ihrem Computer installiert haben. Das liegt daran, dass wp-env eine Docker-Instanz erstellt, auf der eine WordPress-Website ausgeführt wird. Alle am Code vorgenommenen Änderungen werden sofort in der WordPress-Instanz wiedergegeben.

Schritt 2: Installieren Sie @wordpress/env über die Befehlszeile

Wenn Docker und Node.js auf Ihrem Computer ausgeführt werden, können Sie fortfahren und die WordPress-Entwicklungsumgebung installieren.

Sie können wp-env entweder global oder lokal installieren. Um dies global zu tun, müssen Sie den folgenden Befehl aus dem Plugins-Verzeichnis ausführen (mehr dazu im Hinweisfeld „Wichtig“ unten):

 npm install -g @wordpress/env

Lassen Sie uns das aufschlüsseln:

• npm install installiert das Paket.
• -g an den Befehl angehängt installiert das angegebene Paket global.
• @wordpress/env ist das Paket, das Sie installieren werden.

Führen Sie den folgenden Befehl aus, um zu bestätigen, dass wp-env erfolgreich installiert wurde:

 wp-env --version

Sie sollten die aktuelle wp-env Version sehen, was bedeutet, dass Sie die Umgebung jetzt mit dem folgenden Befehl aus dem Ordner Ihres Plugins starten können:

 wp-env start

Sie können auf das WordPress-Dashboard über die folgende Adresse zugreifen:

• http://localhost:8888/wp-admin/

Die Standardanmeldeinformationen lauten wie folgt:

• Benutzername: admin
• Passwort: password

Richten Sie Ihr Block-Plugin ein

Jetzt brauchen Sie ein Starter-Block-Plugin, auf dem Sie aufbauen können. Aber anstatt manuell ein Entwicklungsblock-Plug-in mit allen erforderlichen Dateien und Ordnern zu erstellen, können Sie einfach ein Entwicklungstool ausführen, das alle Dateien und Konfigurationen bereitstellt, die Sie für den Einstieg in die Blockentwicklung benötigen.

Auch hier haben Sie ein paar Optionen zur Auswahl. Werfen wir einen Blick auf jeden.

Option 1: Einrichten eines Block-Plugins mit @wordpress/create-block

@wordpress/create-block ist das offizielle Zero-Configuration-Tool zum Erstellen von Gutenberg-Blöcken:

Block erstellen ist eine offiziell unterstützte Methode zum Erstellen von Blöcken zum Registrieren eines Blocks für ein WordPress-Plugin. Es bietet ein modernes Build-Setup ohne Konfiguration. Es generiert PHP-, JS-, CSS-Code und alles andere, was Sie zum Starten des Projekts benötigen.

Es ist weitgehend von create-react-app inspiriert. Großes Lob an @gaearon, das gesamte Facebook-Team und die React-Community.

Sobald Ihre lokale Umgebung betriebsbereit ist, können Sie einen Starterblock einrichten, indem Sie einfach den npx @wordpress/create-block , der alle Dateien und Ordner bereitstellt, die Sie zum Erstellen des Plugin-Gerüsts und zum Registrieren eines neuen Blocks benötigen .

Lassen Sie uns einen Test durchführen, um zu sehen, wie es funktioniert.

Navigieren Sie in Ihrem Befehlszeilentool zum Verzeichnis /wp-content/plugins/ und führen Sie den folgenden Befehl aus:

 npx @wordpress/create-block my-first-block

Wenn Sie zur Bestätigung aufgefordert werden, geben Sie y ein, um fortzufahren:

Der Vorgang dauert einige Augenblicke. Wenn es fertig ist, sollten Sie die folgende Antwort erhalten:

Und das ist es!

Starten Sie nun Ihre WordPress-Entwicklungsumgebung und gehen Sie zum Plugins -Bildschirm im WordPress-Dashboard. Ein neues Plugin namens „My First Block“ sollte Ihrer Plugin-Liste hinzugefügt worden sein:

Aktivieren Sie das Plugin bei Bedarf, erstellen Sie einen neuen Blog-Beitrag, scrollen Sie im Block-Inserter nach unten zum Abschnitt „ Widgets “ und wählen Sie Ihren neuen Block aus:

Gehen Sie nun zurück zum Terminal und ändern Sie das aktuelle Verzeichnis in my-first-block :

 cd my-first-block

Führen Sie dann den folgenden Befehl aus:

 npm start

Dadurch können Sie das Plugin im Entwicklungsmodus ausführen. Um den Produktionscode zu erstellen, sollten Sie den folgenden Befehl verwenden:

 npm run build

Option 2: Einrichten eines Block-Plugins mit create-guten-block

create-guten-block ist ein Entwicklungstool eines Drittanbieters zum Erstellen von Gutenberg-Blöcken:

create-guten-block ist ein Zero Configuration Dev-Toolkit (#0CJS), um WordPress Gutenberg-Blöcke in wenigen Minuten zu entwickeln, ohne React, Webpack, ES6/7/8/Next, ESLint, Babel usw. zu konfigurieren.

Genau wie das offizielle create-block Tool basiert create-guten-block auf create-react-app und kann Ihnen dabei helfen, Ihr erstes Block-Plugin problemlos zu generieren.

Das Toolkit bietet alles, was Sie zum Erstellen eines modernen WordPress-Plugins benötigen, einschließlich der folgenden:

• React-, JSX- und ES6-Syntaxunterstützung.
• Webpack-Entwicklungs-/Produktions-Build-Prozess hinter den Kulissen.
• Sprachextras jenseits von ES6 wie der Object-Spread-Operator.
• CSS mit automatischem Präfix, sodass Sie kein -webkit oder andere Präfixe benötigen.
• Ein Build-Skript zum Bündeln von JS, CSS und Bildern für die Produktion mit Source-Maps.
• Problemlose Updates für die oben genannten Tools mit einer einzigen Abhängigkeit cgb-scripts.

Beachten Sie die folgende Einschränkung:

Der Nachteil besteht darin, dass diese Tools für eine bestimmte Funktionsweise vorkonfiguriert sind. Wenn Ihr Projekt mehr Anpassungen erfordert, können Sie es „auswerfen“ und anpassen, aber dann müssen Sie diese Konfiguration beibehalten.

Sobald Sie eine lokale WordPress-Website zur Hand haben, starten Sie Ihr Befehlszeilentool, navigieren Sie zum Ordner /wp-content/plugins Ihrer Installation und führen Sie den folgenden Befehl aus:

 npx create-guten-block my-first-block

Sie müssen ein oder zwei Minuten warten, während die Projektstruktur erstellt und Abhängigkeiten heruntergeladen werden:

Wenn der Vorgang abgeschlossen ist, sollten Sie den folgenden Bildschirm sehen:

Dieses nächste Bild zeigt die Projektstruktur, wobei das Terminal in Visual Studio Code ausgeführt wird:

Gehen Sie nun zurück zu Ihrem WordPress-Dashboard. Ein neues Element sollte im Plugins-Bildschirm aufgelistet werden – es ist das my-first-block- Plugin:

Aktivieren Sie das Plugin und gehen Sie zurück zum Terminal. Ändern Sie das aktuelle Verzeichnis in my-first-block und führen Sie dann npm start aus:

 cd my-first-block npm start

Sie sollten die folgende Antwort erhalten:

Auch dies ermöglicht es Ihnen, das Plugin im Entwicklungsmodus auszuführen. Um den Produktionscode zu erstellen, sollten Sie Folgendes verwenden:

 npm run build

Aktivieren Sie das Plugin und erstellen Sie einen neuen Beitrag oder eine neue Seite, durchsuchen Sie dann Ihre Blöcke und wählen Sie Ihren brandneuen Gutenberg-Block aus:

Für eine tiefergehende Übersicht oder bei Fehlern sei auf die von Ahmad Awais bereitgestellte Dokumentation verwiesen.

Eine exemplarische Vorgehensweise des Starterblock-Gerüsts

Unabhängig davon, für welches der beiden Entwicklungstools – create-block oder create-guten-block – Sie sich entscheiden, haben Sie jetzt ein Blockgerüst, das Sie als Ausgangspunkt zum Erstellen eines Block-Plugins verwenden können.

Doch was genau ist ein Blockgerüst?

Block Scaffolding ist ein Kurzbegriff, der die unterstützende Verzeichnisstruktur beschreibt, die WordPress benötigt, um einen Block zu erkennen. Typischerweise enthält dieses Verzeichnis Dateien wie index.php , index.js , style.css und andere – die wiederum Aufrufe wie register_block_type enthalten.

Wir haben uns für das offizielle Create Block Dev-Tool entschieden, wie es im Block Editor Handbook verwendet wird. Aber selbst wenn Sie sich für ein Drittanbieter-Tool wie create-guten-block entscheiden, wird Ihre Erfahrung nicht allzu anders sein.

Lassen Sie uns vor diesem Hintergrund tiefer in das Tool zum create-block von Blöcken eintauchen.

Ein genauerer Blick auf das Create Block Dev-Tool

Wie oben erwähnt, ist Create Block das offizielle Befehlszeilentool zum Erstellen von Gutenberg-Blöcken. Wenn Sie @wordpress/create-block in Ihrem Terminal ausführen, werden die PHP-, JS- und SCSS-Dateien und der Code generiert, die zum Registrieren eines neuen Blocktyps erforderlich sind:

 npx @wordpress/create-block [options] [slug]

• [slug] (optional) – wird verwendet, um den Block-Slug zuzuweisen und das Plugin zu installieren
• [options] (optional) — verfügbare Optionen

Standardmäßig wird eine ESNext-Vorlage zugewiesen. Das bedeutet, dass Sie die nächste Version von JavaScript mit dem Zusatz der JSX-Syntax erhalten.

Wenn Sie den Blocknamen weglassen, wird der Befehl im interaktiven Modus ausgeführt, sodass Sie mehrere Optionen anpassen können, bevor Sie die Dateien generieren:

 npx @wordpress/create-block

Das folgende Bild zeigt die Dateistruktur eines Block-Plugins, das mit dem offiziellen Create Block-Tool erstellt wurde:

Lassen Sie uns die wichtigsten Dateien und Ordner unseres neuen Block-Plugins durchgehen.

Die Plugin-Datei

Mit der Haupt-Plugin-Datei registrierst du den Block auf dem Server:

 /** * Plugin Name: My First Block * Description: Example block written with ESNext standard and JSX support – build step required. * Requires at least: 5.8 * Requires PHP: 7.0 * Version: 0.1.0 * Author: The WordPress Contributors * License: GPL-2.0-or-later * License URI: https://www.gnu.org/licenses/gpl-2.0.html * Text Domain: my-first-block * * @package create-block */ /** * Registers the block using the metadata loaded from the `block.json` file. * Behind the scenes, it registers also all assets so they can be enqueued * through the block editor in the corresponding context. * * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/ */ function create_block_my_first_block_block_init() { register_block_type( __DIR__ ); } add_action( 'init', 'create_block_my_first_block_block_init' );

Die Funktion register_block_type registriert einen Blocktyp auf dem Server unter Verwendung der in der Datei block.json gespeicherten Metadaten.

Die Funktion benötigt zwei Parameter:

• Der Name des Blocktyps einschließlich Namespace oder ein Pfad zu dem Ordner, in dem sich die Datei block.json befindet, oder ein vollständiges WP_Block_Type Objekt
• Ein Array von Blockargumenten

Im obigen Code wird das Blocktypargument von der magischen Konstante __DIR__ bereitgestellt. Das bedeutet, dass sich die Datei block.json im selben Ordner wie die Datei des Plugins befindet.

Die Datei „package.json“.

Die Datei „package.json“ definiert JavaScript-Eigenschaften und -Skripts für Ihr Projekt. Hier können Sie Ihre Projektabhängigkeiten installieren.

Um besser zu verstehen, wofür diese Datei gedacht ist, öffnen Sie sie mit Ihrem bevorzugten Code-Editor:

 { "name": "my-first-block", "version": "0.1.0", "description": "Example block written with ESNext standard and JSX support – build step required.", "author": "The WordPress Contributors", "license": "GPL-2.0-or-later", "main": "build/index.js", "scripts": { "build": "wp-scripts build", "format": "wp-scripts format", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "start": "wp-scripts start", "packages-update": "wp-scripts packages-update" }, "dependencies": { "@wordpress/block-editor": "^7.0.1", "@wordpress/blocks": "^11.0.1", "@wordpress/i18n": "^4.2.1" }, "devDependencies": { "@wordpress/scripts": "^18.0.0" } }

Die Eigenschaft scripts ist ein Wörterbuch, das Befehle enthält, die zu verschiedenen Zeiten im Lebenszyklus eines Pakets mit npm run [cmd] werden.

In diesem Artikel verwenden wir die folgenden Befehle:

• npm run build – erstellt einen (komprimierten) Produktions-Build
• npm run start – erstellt einen (unkomprimierten) Entwicklungs-Build

dependencies und devDependencies sind zwei Objekte, die einen Paketnamen einer Version zuordnen. dependencies sind in der Produktion erforderlich, während devDependences nur für die lokale Entwicklung benötigt werden (lesen Sie mehr).

Die einzige standardmäßige Entwicklerabhängigkeit ist das @wordpress/scripts -Paket, das als „eine Sammlung wiederverwendbarer Skripte, die auf die WordPress-Entwicklung zugeschnitten sind“ definiert ist.

Die block.json-Datei

Ab WordPress 5.8 ist die block.json- Metadatendatei die kanonische Methode zum Registrieren von Blocktypen.

Eine block.json -Datei bietet mehrere Vorteile, darunter eine verbesserte Leistung und eine bessere Sichtbarkeit im WordPress-Plugins-Verzeichnis:

Aus Performance-Sicht, wenn Themes verzögertes Laden von Assets unterstützen, wird bei Blöcken, die mit block.json registriert sind, das Enqueuing ihrer Assets sofort optimiert. Die in den style oder script aufgeführten Front-End-CSS- und -JavaScript-Assets werden nur in die Warteschlange eingereiht, wenn der Block auf der Seite vorhanden ist, was zu reduzierten Seitengrößen führt.

Durch Ausführen des Befehls @wordpress/create-block wird die folgende block.json -Datei generiert:

 { "apiVersion": 2, "name": "create-block/my-first-block", "version": "0.1.0", "title": "My First Block", "category": "widgets", "icon": "smiley", "description": "Example block written with ESNext standard and JSX support – build step required.", "supports": { "html": false }, "textdomain": "my-first-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Hier ist die vollständige Liste der Standardeigenschaften:

• apiVersion — die Version der vom Block verwendeten API (aktuelle Version ist 2)
• name – eine eindeutige Kennung für einen Block, einschließlich eines Namensraums
• version — die aktuelle Version eines Blocks
• title — ein Anzeigetitel für einen Block
• category – eine Blockkategorie
• icon — ein Dashicon-Slug oder ein benutzerdefiniertes SVG-Icon
• description — eine kurze Beschreibung, die im Blockinspektor sichtbar ist
• supports – eine Reihe von Optionen zur Steuerung von Funktionen, die im Editor verwendet werden
• textdomain — die Textdomain des Plugins
• editorScript — Definition des Editorskripts
• editorStyle — Definition des Editorstils
• style — bietet alternative Stile für einen Block

Zusätzlich zu den oben aufgeführten Eigenschaften können (und werden Sie wahrscheinlich) ein attributes -Objekt definieren, das Informationen über die von Ihrem Block gespeicherten Daten bereitstellt. In Ihrer block.json können Sie eine beliebige Anzahl von Attributen in Schlüssel/Wert -Paaren festlegen, wobei der Schlüssel der Attributname und der Wert die Attributdefinition ist.

Sehen Sie sich das folgende Beispiel für Attributdefinitionen an:

 "attributes": { "content": { "type": "array", "source": "children", "selector": "p" }, "align": { "type": "string", "default": "none" }, "link": { "type": "string", "default": "https://kinsta.com" } },

Wir werden später in diesem Artikel tiefer in die block.json -Datei eintauchen, aber Sie können auch das Block-Editor-Handbuch für detailliertere Informationen zu block.json- Metadaten und -Attributen lesen.

Der src-Ordner

Der src Ordner ist der Ort, an dem die Entwicklung stattfindet. In diesem Ordner finden Sie die folgenden Dateien:

• index.js
• edit.js
• save.js
• editor.scss
• style.scss

index.js

Die Datei index.js ist Ihr Ausgangspunkt. Hier importieren Sie Abhängigkeiten und registrieren den Blocktyp auf dem Client:

 import { registerBlockType } from '@wordpress/blocks'; import './style.scss'; import Edit from './edit'; import save from './save'; registerBlockType('create-block/my-first-block', { edit: Edit, save, });

Die erste Anweisung importiert die Funktion registerBlockType aus dem Paket @wordpress/blocks . Die folgenden import-Anweisungen importieren das Stylesheet zusammen mit den Edit und save Funktionen.

Die Funktion registerBlockType registriert die Komponente auf dem Client. Die Funktion benötigt zwei Parameter: einen Blocknamen namespace/block-name (derselbe wie auf dem Server registriert) und ein Blockkonfigurationsobjekt.

Die Funktion „ Edit “ stellt die Blockschnittstelle bereit, wie sie im Blockeditor gerendert wird, während die Funktion „ save “ die Struktur bereitstellt, die serialisiert und in der Datenbank gespeichert wird (lesen Sie mehr).

edit.js

In edit.js erstellen Sie die Blockverwaltungsschnittstelle:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Zuerst importiert es die Funktion __ aus dem Paket @wordpress/i18n (dieses Paket enthält eine JavaScript-Version der Übersetzungsfunktionen), den Hook useBlockProps React und die Datei editor.scss .

Anschließend exportiert es die React-Komponente (lesen Sie mehr über Import- und Exportanweisungen).

save.js

In der Datei save.js erstellen wir die Blockstruktur, die in der Datenbank gespeichert werden soll:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; export default function save() { return ( <p {...useBlockProps.save()}> {__( 'My First Block – hello from the saved content!', 'my-first-block' )} </p> ); }

editor.scss und style.scss

Abgesehen von den Skripten befinden sich zwei SASS-Dateien in den src- Ordnern. Die Datei „editor.scss “ enthält die Stile, die im Kontext des Editors auf den Block angewendet werden, während die Datei „ style.scss “ die Stile des Blocks zur Anzeige im Frontend enthält. Wir werden im zweiten Teil dieses Handbuchs tiefer in diese Dateien eintauchen.

Die Ordner node_modules und build

Der Ordner node_modules enthält Knotenmodule und ihre Abhängigkeiten. Wir werden nicht näher auf Node-Pakete eingehen, da dies den Rahmen dieses Artikels sprengen würde, aber Sie können in diesem Artikel mehr darüber lesen, wo npm die Pakete installiert.

Der build -Ordner enthält die aus dem Build-Prozess resultierenden JS- und CSS-Dateien. In den ESNext-Syntax- und JavaScript-Build-Setup-Anleitungen können Sie tiefer in den Build-Prozess eintauchen.

Das Projekt: Bauen Sie Ihren ersten Gutenberg-Block

Es ist Zeit, uns die Hände schmutzig zu machen. In diesem Abschnitt erfahren Sie, wie Sie ein Plugin erstellen, das einen CTA-Block namens Affiliate Block bereitstellt.

Der Block besteht aus zwei Spalten, mit einem Bild auf der linken Seite und einem Textabsatz auf der rechten Seite. Unter dem Text wird eine Schaltfläche mit einem anpassbaren Link platziert:

Dies ist nur ein einfaches Beispiel, aber es ermöglicht uns, die Grundlagen der Entwicklung von Gutenberg-Blöcken zu behandeln. Sobald Sie die Grundlagen klar verstanden haben, können Sie fortfahren und immer komplexere Gutenberg-Blöcke mit Hilfe des Blockeditor-Handbuchs und anderer der umfangreichen verfügbaren Ressourcen erstellen.

Angenommen, Sie haben die neueste Version von WordPress auf Ihrer lokalen Entwicklungsumgebung ausgeführt, werden Sie von hier an Folgendes lernen:

• So richten Sie das Starter-Block-Plugin ein
• block.json bei der Arbeit
• Verwenden von integrierten Komponenten: Die RichText-Komponente
• Hinzufügen von Steuerelementen zur Blocksymbolleiste
• Anpassen der Blockeinstellungen-Seitenleiste
• Hinzufügen und Anpassen eines externen Links
• Hinzufügen mehrerer Blockstile
• Verschachteln von Blöcken mit der InnerBlocks-Komponente
• Zusätzliche Verbesserungen

Achtung, fertig, los!

So richten Sie das Starter-Block-Plugin ein

Starten Sie Ihr Befehlszeilentool und navigieren Sie zum Ordner /wp-content/plugins :

Führen Sie nun den folgenden Befehl aus:

 npx @wordpress/create-block

Dieser Befehl generiert die PHP-, SCSS- und JS-Dateien zum Registrieren eines Blocks im interaktiven Modus, sodass Sie die erforderlichen Daten für Ihren Block einfach hinzufügen können. Für unser Beispiel verwenden wir die folgenden Details:

• Block-Slug : mein-Affiliate-Block
• Interner Namensraum : my-affiliate-plugin
• Anzeigetitel des Blocks : Affiliate-Block
• Kurze Blockbeschreibung: Ein Beispielblock für Kinsta-Leser
• Dashicon : Geld
• Kategoriename : Design
• Plugin-Autor : Ihr Name
• Lizenz : –
• Link zum Lizenztext : –
• Aktuelle Plugin-Version : 0.1.0

Die Installation des Plugins und aller Abhängigkeiten dauert einige Minuten. Wenn der Vorgang abgeschlossen ist, sehen Sie die folgende Antwort:

Führen Sie nun den folgenden Befehl aus dem Ordner /wp-content/plugins aus:

 cd my-affiliate-block

Schließlich können Sie im Ordner Ihres Plugins (in unserem Beispiel my-affiliate-block ) mit der Entwicklung beginnen:

 npm start

Öffnen Sie nun den Plugins-Bildschirm, um das Affiliate-Block -Plugin zu finden und zu aktivieren:

Erstellen Sie einen neuen Beitrag, öffnen Sie den Block-Einfüger und scrollen Sie nach unten zur Kategorie Design . Klicken Sie hier, um den Affiliate-Block hinzuzufügen:

block.json bei der Arbeit

Wie bereits erwähnt, findet die serverseitige Blockregistrierung in der Haupt- .php -Datei statt. Wir definieren jedoch keine Einstellungen in der .php -Datei. Stattdessen verwenden wir die Datei block.json .

Öffnen Sie also block.json erneut und sehen Sie sich die Standardeinstellungen genauer an:

 { "apiVersion": 2, "name": "my-affiliate-plugin/my-affiliate-block", "version": "0.1.0", "title": "Affiliate Block", "category": "design", "icon": "money", "description": "An example block for Kinsta readers", "supports": { "html": false }, "textdomain": "my-affiliate-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Skripte und Stile

Die Eigenschaften editorScript , editorStyle und style stellen die relativen Pfade zu Front-End- und Back-End-Skripten und -Stilen bereit.

Sie müssen die hier definierten Skripte und Stile nicht manuell registrieren, da diese automatisch von WordPress registriert und in die Warteschlange gestellt werden. Um das zu beweisen, starten Sie den Browser-Inspektor und öffnen Sie die Registerkarte Netzwerk :

Wie Sie dem obigen Bild entnehmen können, wurde unser index.js- Skript, das sich im Build -Ordner befindet, regelmäßig in die Warteschlange eingereiht , ohne dass PHP-Code hinzugefügt werden musste.

Melden Sie sich für den Newsletter an

Möchten Sie wissen, wie wir unseren Traffic um über 1000 % gesteigert haben?

Schließen Sie sich über 20.000 anderen an, die unseren wöchentlichen Newsletter mit WordPress-Insidertipps erhalten!

Abonniere jetzt

UI-Labels

Die title und description stellen die Bezeichnungen bereit, die zum Identifizieren des Blocks im Editor erforderlich sind:

Schlüsselwörter

Wie bereits erwähnt, können Sie Ihre Blockeinstellungen mithilfe von Eigenschaften und Attributen genau konfigurieren. Sie können beispielsweise ein oder mehrere keywords hinzufügen, um Benutzern beim Suchen von Blöcken zu helfen:

 { "keywords": [ "kinsta", "affiliate", "money" ] }

If you now input “kinsta”, “affiliate” or “money” in the quick inserter, the editor will suggest you the Affiliate block:

Lokalisierung

If you are wondering how the localization of the strings in the JSON file happens, here is the answer:

In JavaScript, you can use now registerBlockTypeFromMetadata method from @wordpress/blocks package to register a block type using the metadata loaded from block.json file. All localized properties get automatically wrapped in _x (from @wordpress/i18n package) function calls similar to how it works in PHP with register_block_type_from_metadata . The only requirement is to set the textdomain property in the block.json file.

Here we are using the registerBlockType function instead of registerBlockTypeFromMetadata , as the latter has been deprecated since Gutenberg 10.7, but the mechanism is the same.

Using Built-In Components: The RichText Component

The elements that make up a Gutenberg block are React components, and you can access these components via the wp global variable. For example, try to type wp.editor into your browser's console. This will give you the full list of the components included in the wp.editor module.

Scroll through the list and guess what components are meant for by their names.

Similarly, you can check the list of components included in the wp.components module:

Now go back to the edit.js file and take a closer look at the script:

import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Dieser Code generiert einen statischen Block mit einfachem, nicht bearbeitbarem Text. Aber wir können die Dinge leicht ändern:

Um den Text bearbeitbar zu machen, müssen Sie das aktuelle <p> -Tag durch eine Komponente ersetzen, die den Eingabeinhalt bearbeitbar macht. Dafür stellt Gutenberg die eingebaute RichText-Komponente zur Verfügung.

Das Hinzufügen einer integrierten Komponente zu Ihrem Block ist ein 5-stufiger Prozess:

1. Importieren Sie die erforderlichen Komponenten aus einem WordPress-Paket
2. Fügen Sie die entsprechenden Elemente in Ihren JSX-Code ein
3. Definieren Sie die erforderlichen Attribute in der Datei block.json
4. Ereignishandler definieren
5. Daten speichern

Schritt 1: Importieren Sie die erforderlichen Komponenten aus einem WordPress-Paket

Öffnen Sie nun die Datei edit.js und ändern Sie die folgende import :

 import { useBlockProps } from '@wordpress/block-editor';

…zu:

 import { useBlockProps, RichText } from '@wordpress/block-editor';

Auf diese Weise importieren Sie die useBlockProps Funktion und die RichText Komponente aus dem Paket @wordpress/block-editor .

Verwenden Sie BlockProps

Der Hook useBlockProps React markiert das Wrapper-Element des Blocks:

Wenn Sie API-Version 2 verwenden, müssen Sie den neuen useBlockProps Hook in der edit des Blocks verwenden, um das Wrapper-Element des Blocks zu markieren. Der Hook fügt Attribute und Ereignishandler ein, die zum Aktivieren des Blockverhaltens erforderlich sind. Alle Attribute, die Sie an das Blockelement übergeben möchten, müssen über useBlockProps und der zurückgegebene Wert auf das Element verteilt werden.

Vereinfacht gesagt weist useBlockProps dem Wrapper-Element (in unserem Beispiel dem p -Element) automatisch Attribute und Klassen zu:

Wenn Sie useBlockProps aus dem Wrapper-Element entfernen, hätten Sie eine einfache Textzeichenfolge ohne Zugriff auf Blockfunktionalität und -stil:

Wie wir später erklären werden, können Sie auch ein Objekt mit Eigenschaften an useBlockProps übergeben, um die Ausgabe anzupassen.

RichText

Die RichText-Komponente bietet eine inhaltsveränderbare Eingabe, mit der Benutzer den Inhalt bearbeiten und formatieren können.

Sie finden die Komponente dokumentiert auf GitHub unter gutenberg/packages/block-editor/src/components/rich-text/README.md.

Schritt 2: Fügen Sie die entsprechenden Elemente in Ihren JSX-Code ein

 ... const blockProps = useBlockProps(); return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> );

Kommentieren wir den Code Zeile für Zeile:

• tagName — der Tag-Name des bearbeitbaren HTML-Elements
• onChange — Funktion, die aufgerufen wird, wenn sich der Inhalt des Elements ändert
• allowedFormats — ein Array erlaubter Formate. Standardmäßig sind alle Formate erlaubt
• value — die HTML-Zeichenfolge, die bearbeitbar gemacht werden soll
• placeholder — Platzhaltertext, der angezeigt wird, wenn das Element leer ist

Schritt 3: Definieren Sie die erforderlichen Attribute in der Datei block.json

Attribute geben Auskunft über die von einem Block gespeicherten Daten, wie z. B. Rich Content, Hintergrundfarbe, URLs usw.

Sie können eine beliebige Anzahl von Attributen innerhalb eines attributes -Objekts in Schlüssel/Wert-Paaren festlegen, wobei der Schlüssel der Attributname und der Wert die Attributdefinition ist.

Öffnen Sie nun die Datei block.json und fügen Sie die folgenden attributes prop hinzu:

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" } },

Das content ermöglicht es, den vom Benutzer eingegebenen Text im bearbeitbaren Feld zu speichern:

• type gibt den Datentyp an, der von dem Attribut gespeichert wird. Der Typ ist erforderlich, es sei denn, Sie definieren eine enum .
• source definiert, wie der Attributwert aus dem Beitragsinhalt extrahiert wird. In unserem Beispiel ist es der HTML-Inhalt. Beachten Sie, dass Daten im Blocktrennzeichen gespeichert werden, wenn Sie keine Quelleigenschaft angeben (lesen Sie mehr).
• selector ist ein HTML-Tag oder ein beliebiger anderer Selektor, wie z. B. ein Klassenname oder ein id-Attribut.

Wir werden der Edit -Funktion ein Objekt mit Eigenschaften übergeben. Gehen Sie also zurück zur Datei edit.js und nehmen Sie die folgende Änderung vor:

 export default function Edit( { attributes, setAttributes } ) { ... }

Schritt 4: Ereignishandler definieren

Das RichText Element hat ein onChange -Attribut, das eine Funktion bereitstellt, die aufgerufen wird, wenn sich der Inhalt des Elements ändert.

Lassen Sie uns diese Funktion definieren und das gesamte edit.js- Skript anzeigen:

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> ); }

Speichern Sie nun die Datei und führen Sie npm run start in Ihrem Terminalfenster aus. Gehen Sie dann zurück zu Ihrem WordPress-Dashboard, erstellen Sie einen neuen Beitrag oder eine neue Seite und fügen Sie Ihren Affiliate-Block hinzu:

Fügen Sie Text hinzu und wechseln Sie zur Codeansicht. So sollte Ihr Code aussehen:

 <!-- wp:my-affiliate-plugin/my-affiliate-block --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable Gutenberg block </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Wenn Sie jetzt die Seite speichern und das Frontend-Ergebnis überprüfen, werden Sie möglicherweise etwas enttäuscht sein, da Ihre Änderungen die Website nicht betreffen. Das liegt daran, dass Sie die Datei save.js ändern müssen, um Benutzereingaben in der Datenbank zu speichern, wenn der Beitrag gespeichert wird.

Schritt 5: Daten speichern

Öffnen Sie nun die Datei save.js und ändern Sie das Skript wie folgt:

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } /> ); }

Das machen wir hier:

• Importieren Sie die RichText -Komponente aus dem block-editor Paket.
• Übergeben Sie mehrere Eigenschaften über ein Objektargument an die save (in diesem Beispiel übergeben wir nur die Eigenschaft attributes ).
• Gibt den Inhalt der RichText Komponente zurück

Sie können mehr über die RichText Komponente im Blockeditor-Handbuch lesen und die vollständige Liste der Requisiten auf Github finden.

Gehen wir jetzt noch einen Schritt weiter. Im nächsten Abschnitt erfahren Sie, wie Sie der Blocksymbolleiste Steuerelemente hinzufügen.

Hinzufügen von Steuerelementen zur Blocksymbolleiste

Die Blocksymbolleiste enthält eine Reihe von Steuerelementen, mit denen Benutzer Teile des Blockinhalts bearbeiten können. Für jedes Symbolleisten-Steuerelement finden Sie eine Komponente:

Sie könnten beispielsweise eine Textausrichtungssteuerung für Ihren Block hinzufügen. Alles, was Sie tun müssen, ist, zwei Komponenten aus dem Paket @wordpress/block-editor zu importieren.

Wir gehen die gleichen Schritte wie im vorherigen Beispiel durch:

1. Erforderliche Komponenten aus WordPress-Paketen importieren
2. Fügen Sie die entsprechenden Elemente in Ihren JSX-Code ein
3. Definieren Sie die erforderlichen Attribute in der Datei block.json
4. Definieren Sie Event-Handler
5. Daten speichern

Schritt 1: Importieren Sie BlockControls und AlignmentControl-Komponenten aus @wordpress/block-editor

Um der Blocksymbolleiste ein Ausrichtungssteuerelement hinzuzufügen, benötigen Sie zwei Komponenten:

• BlockControls rendert eine dynamische Symbolleiste mit Steuerelementen (nicht dokumentiert).
• AlignmentControl rendert ein Dropdown-Menü, das Ausrichtungsoptionen für den ausgewählten Block anzeigt (weiterlesen)

Öffnen Sie die Datei edit.js und bearbeiten Sie die import -Anweisung wie unten gezeigt:

 import { useBlockProps, RichText, AlignmentControl, BlockControls } from '@wordpress/block-editor';

Schritt 2: Fügen Sie BlockControls und AlignmentControl-Elemente hinzu

Gehen Sie zur Funktion Edit und fügen Sie das Element <BlockControls /> auf der gleichen Ebene wie <RichText /> . Fügen Sie dann und <AlignmentControl /> innerhalb <BlockControls /> :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

Im obigen Code sind <> und </> die kurze Syntax zum Deklarieren von React-Fragmenten, wodurch wir mehrere Elemente in React zurückgeben.

In diesem Beispiel hat AlignmentControl zwei Attribute:

• value liefert den aktuellen Wert für das Element
• onChange stellt einen Ereignishandler bereit, der ausgeführt wird, wenn sich der Wert ändert

Wir haben auch zusätzliche Attribute für das RichText Element definiert (überprüfen Sie die vollständige Liste der Attribute mit Beispielen).

Schritt 3: Definieren Sie das align-Attribut in block.json

Gehen Sie nun zur Datei block.json und fügen Sie das align -Attribut hinzu:

 "align": { "type": "string", "default": "none" }

Gehen Sie zurück zum Terminal, stoppen Sie den aktuellen Prozess mit ^C und starten Sie das Skript erneut mit npm run start . Gehen Sie dann zurück zum Blockeditor, aktualisieren Sie die Seite und wählen Sie den Block aus. Sie sollten die Blocksymbolleiste mit einer Ausrichtungssteuerung sehen:

Wenn Sie jetzt versuchen, den Blockinhalt mit den neuen Ausrichtungssteuerelementen zu formatieren, werden Sie feststellen, dass nichts passiert. Das liegt daran, dass wir den Event-Handler noch nicht definiert haben.

Schritt 4: Definieren Sie die Event-Handler

Definieren Sie nun onChangeAlign :

 const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) }

Wenn newAlign undefined ist, setzen wir newAlign auf none . Andernfalls verwenden wir newAlign .

Unser edit.js- Skript sollte (vorerst) vollständig sein:

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

Jetzt können Sie zurück zum Editor gehen und den Blockinhalt ausrichten.

Wir müssen die Speicherfunktion ändern, um Blockinhalte und Attribute in der Datenbank zu speichern.

Schritt 5: Daten speichern

Öffnen Sie save.js und ändern Sie die save wie folgt:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } style={ { textAlign: attributes.align } } /> ); }

Um den Code lesbarer zu machen, können Sie schließlich die einzelnen Eigenschaften aus dem attribute mithilfe der destrukturierenden Zuweisungssyntax extrahieren:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align } } /> ); }

Speichern Sie die Datei, starten Sie den Prozess neu und kehren Sie im Code-Editor-Modus zum Editor zurück. Der Code sollte in etwa so aussehen:

 <!-- wp:my-affiliate-plugin/my-affiliate-block {"align":"right"} --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable <strong><em>Gutenberg</em></strong> <em>block</em> </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Und das ist es! Sie haben der Blocksymbolleiste gerade ein Ausrichtungssteuerelement hinzugefügt

Sie können mehr über Blocksymbolleisten-Steuerelemente im Blockeditor-Handbuch lesen.

Anpassen der Blockeinstellungen-Seitenleiste

Sie können der Seitenleiste der Blockeinstellungen auch Steuerelemente hinzufügen (oder sogar eine neue Seitenleiste für Ihre Anwendung erstellen).

Die API stellt dafür eine InspectorControls -Komponente bereit.

Das Handbuch zum Blockeditor erklärt die Verwendung der Seitenleiste „Einstellungen“:

Die Seitenleiste „Einstellungen“ wird verwendet, um weniger häufig verwendete Einstellungen oder Einstellungen anzuzeigen, die mehr Platz auf dem Bildschirm benötigen. Die Seitenleiste „Einstellungen“ sollte nur für Einstellungen auf Blockebene verwendet werden .

Wenn Sie Einstellungen haben, die sich nur auf ausgewählte Inhalte innerhalb eines Blocks auswirken (Beispiel: die Einstellung „Fett“ für ausgewählten Text in einem Absatz): platzieren Sie sie nicht in der Seitenleiste „Einstellungen“. Die Seitenleiste „Einstellungen“ wird auch angezeigt, wenn ein Block im HTML-Modus bearbeitet wird, sodass sie nur Einstellungen auf Blockebene enthalten sollte.

Wieder:

1. Erforderliche Komponenten aus WordPress-Paketen importieren
2. Fügen Sie die entsprechenden Elemente in Ihren JSX-Code ein
3. Definieren Sie die erforderlichen Attribute in der Datei block.json
4. Definieren Sie Event-Handler
5. Daten speichern

Schritt 1. Importieren Sie InspectorControls- und PanelColorSettings-Komponenten aus @wordpress/block-editor

Sie können mehrere Steuerelemente hinzufügen, damit Benutzer bestimmte Aspekte des Blocks anpassen können. Beispielsweise können Sie ein Farbbedienfeld bereitstellen. Dazu müssen Sie die Komponenten InspectorControls und PanelColorSettings aus dem Blockeditor block-editor Modul importieren:

 import { useBlockProps, RichText, AlignmentControl, BlockControls, InspectorControls, PanelColorSettings } from '@wordpress/block-editor';

Schritt 2: Fügen Sie die entsprechenden Elemente in Ihren JSX-Code ein

Nun können Sie dem von der Edit Funktion zurückgegebenen JSX die entsprechenden Elemente hinzufügen:

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <InspectorControls> <PanelColorSettings title={ __( 'Color settings', 'my-affiliate-block' ) } initialOpen={ false } colorSettings={ [ { value: textColor, onChange: onChangeTextColor, label: __( 'Text color', 'my-affiliate-block' ), }, { value: backgroundColor, onChange: onChangeBackgroundColor, label: __( 'Background color', 'my-affiliate-block' ), } ] } /> </InspectorControls> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> </> ); }

Beachten Sie, dass wir auch das style Attribut des RichText Elements aktualisiert haben:

 <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } />

Schritt 3: Definieren Sie die erforderlichen Attribute in block.json

Definieren Sie nun die Attribute backgroundColor und textColor in der Datei block.json :

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" }, "align": { "type": "string", "default": "none" }, "backgroundColor": { "type": "string" }, "textColor": { "type": "string" } },

Schritt 4: Definieren Sie die Event-Handler

Jetzt müssen Sie zwei Funktionen definieren, um backgroundColor und textColor bei Benutzereingaben zu aktualisieren:

 const onChangeBackgroundColor = ( newBackgroundColor ) => { setAttributes( { backgroundColor: newBackgroundColor } ) } const onChangeTextColor = ( newTextColor ) => { setAttributes( { textColor: newTextColor } ) }

Schritt 5: Daten speichern

Ein letzter Schritt: Öffnen Sie die Datei save.js und ändern Sie das Skript wie folgt:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align, backgroundColor, textColor } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> ); }

Stoppen Sie nun den Prozess (^C) und führen npm run start erneut aus. Aktualisieren Sie die Seite, löschen Sie alle Instanzen Ihres Blocks und fügen Sie ihn erneut zu Ihrem Beitrag hinzu:

Nehmen Sie Ihre Änderungen vor, speichern Sie den Beitrag und sehen Sie ihn im Frontend an. Die Änderungen, die Sie im Blockeditor vorgenommen haben, sollten sich auf der Startseite widerspiegeln.

Hinzufügen und Anpassen eines externen Links

In diesem Abschnitt fügen Sie Ihrem Blocktyp neue Komponenten hinzu:

• Eine ExternalLink -Komponente, mit der Benutzer einen anpassbaren Link zum Affiliate-Block hinzufügen können
• Mehrere Seitenleisten-Steuerelemente, mit denen Benutzer die Link-Einstellungen anpassen können

Schritt 1. Importieren Sie Komponenten aus @wordpress/components

Jetzt müssen Sie mehrere Komponenten aus @wordpress/components importieren. Öffnen Sie Ihre edit.js-Datei und fügen Sie die folgende import hinzu:

 import { TextControl, PanelBody, PanelRow, ToggleControl, ExternalLink } from '@wordpress/components';

• PanelBody fügt einen zusammenklappbaren Container zur Seitenleiste „Einstellungen“ hinzu.
• PaneRow erzeugt einen generischen Container für Sidebar-Steuerelemente.
• TextControl stellt ein Texteingabesteuerelement bereit.
• ToggleControl bietet einen Schalter, mit dem Benutzer eine bestimmte Option aktivieren/deaktivieren können
• ExternalLink ist eine einfache Komponente, um einen externen Link hinzuzufügen.

Schritt 2. Fügen Sie die entsprechenden Elemente in Ihren JSX-Code ein

Zuerst fügen Sie das ExternalLink -Element auf derselben Ebene von RichText in einem div -Container hinzu:

 <div { ...blockProps }> <RichText ... /> <ExternalLink href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "" } > { linkLabel } </ExternalLink> </div>

Die ExternalLink Komponente ist nicht dokumentiert, daher haben wir auf die Komponente selbst verwiesen, um die Liste der verfügbaren Attribute zu erhalten. Hier verwenden wir die Attribute href , className und rel .

Standardmäßig ist der Wert des Attributs rel auf noopener noreferrer . Unser Code fügt das nofollow -Schlüsselwort zum rel -Attribut des resultierenden a -Tags hinzu, wenn das Umschaltsteuerelement aktiviert ist .

Jetzt können Sie der Block-Seitenleiste Link-Einstellungen hinzufügen.

Zuerst fügen Sie ein PanelBody Element in InspectorControls auf derselben Ebene wie PanelColorSettings :

 <InspectorControls> <PanelColorSettings ... /> <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > ... </PanelBody> </InspectorControls>

Hier ist, was wir damit machen:

1. Das title Attribut stellt den Panel-Titel bereit.
2. initialOpen legt fest, ob das Panel anfangs geöffnet ist oder nicht.

Als Nächstes fügen wir zwei PanelRow -Elemente in PanelBody und ein TextControl -Element in jedem PanelRow :

 <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > <PanelRow> <fieldset> <TextControl label={__( 'Affiliate link', 'my-affiliate-block' )} value={ affiliateLink } onChange={ onChangeAffiliateLink } help={ __( 'Add your affiliate link', 'my-affiliate-block' )} /> </fieldset> </PanelRow> <PanelRow> <fieldset> <TextControl label={__( 'Link label', 'my-affiliate-block' )} value={ linkLabel } onChange={ onChangeLinkLabel } help={ __( 'Add link label', 'my-affiliate-block' )} /> </fieldset> </PanelRow> </PanelBody>

Der obige Code sollte jetzt ziemlich einfach aussehen. Mit den beiden Textsteuerelementen können Benutzer die Linkbezeichnung und die URL festlegen.

Wir werden auch eine zusätzliche PanelRow mit einem ToggleControl , um eine bestimmte Option ein-/auszuschalten, z. B. ob ein Attribut eingeschlossen werden soll oder nicht:

 <PanelRow> <fieldset> <ToggleControl label="Add rel = nofollow" help={ hasLinkNofollow ? 'Has rel nofollow.' : 'No rel nofollow.' } checked={ hasLinkNofollow } onChange={ toggleNofollow } /> </fieldset> </PanelRow>

Schritt 3: Definieren Sie die erforderlichen Attribute in block.json

Definieren Sie nun die Attribute affiliateLink , linkLabel und hasLinkNofollow in der Datei block.json :

 "affiliateLink": { "type": "string", "default": "" }, "linkLabel": { "type": "string", "default": "Check it out!" }, "hasLinkNofollow": { "type": "boolean", "default": false }

Hier ist nichts mehr hinzuzufügen! Fahren wir mit der Definition der Event-Handling-Funktionen fort.

Schritt 4: Definieren Sie die Event-Handler

Kehren Sie zur Datei edit.js zurück und fügen Sie die folgenden Funktionen hinzu:

 const onChangeAffiliateLink = ( newAffiliateLink ) => { setAttributes( { affiliateLink: newAffiliateLink === undefined ? '' : newAffiliateLink } ) } const onChangeLinkLabel = ( newLinkLabel ) => { setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } ) } const toggleNofollow = () => { setAttributes( { hasLinkNofollow: ! hasLinkNofollow } ) }

Diese Funktionen aktualisieren die entsprechenden Attributwerte bei Benutzereingaben.

Schritt 5: Daten speichern

Zuletzt müssen wir die save in save.js aktualisieren :

 export default function save( { attributes } ) { const { align, content, backgroundColor, textColor, affiliateLink, linkLabel, hasLinkNofollow } = attributes; const blockProps = useBlockProps.save(); return ( <div { ...blockProps }> <RichText.Content tagName="p" value={ content } style={ { backgroundColor: backgroundColor, color: textColor } } /> <p> <a href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" } > { linkLabel } </a> </p> </div> ); }

Beachten Sie, dass wir hier ein reguläres Element a anstelle von ExternalLink verwendet haben:

Speichern Sie nun die Daten und starten Sie Ihre Umgebung neu.

Hinzufügen mehrerer Blockstile

In einem vorherigen Abschnitt haben Sie gelernt, wie Sie ein Blocksymbolleisten-Steuerelement hinzufügen, mit dem Benutzer die Benutzereingabe ausrichten können. Wir können der Blocksymbolleiste weitere Stilsteuerelemente hinzufügen, aber wir können auch eine Reihe vordefinierter Blockstile bereitstellen, aus denen der Benutzer mit einem einzigen Klick auswählen kann.

Zu diesem Zweck verwenden wir eine nützliche Funktion der Block-API: Blockstile.

Alles, was Sie tun müssen, ist die Eigenschaft block.json styles zu definieren und die entsprechenden Styles in Ihren Stylesheets zu deklarieren.

Sie können beispielsweise das folgende Array von Stilen hinzufügen:

 "styles": [ { "name": "default", "label": "Default", "isDefault": true }, { "name": "border", "label": "Border" } ],

Damit haben Sie gerade einen Standardstil und einen zusätzlichen Stil namens border hinzugefügt. Gehen Sie nun zurück zum Blockeditor:

Die Stile sind für den Benutzer verfügbar, indem er auf den Blockumschalter klickt und dann in der Blockeinstellungen-Seitenleiste nach dem Stile-Bedienfeld sucht.

Wählen Sie einen Stil aus und überprüfen Sie die auf das p -Element angewendeten Klassen. Klicken Sie mit der rechten Maustaste auf den Block und prüfen Sie . Es wurde eine neue Klasse mit folgendem Namen hinzugefügt:

 is-style-{style-name}

Wenn Sie den Stil „Border“ aktiviert haben, wird dem p -Element eine is-style-border Klasse hinzugefügt. Wenn Sie den Stil „Standard“ aktiviert haben, wird stattdessen eine Klasse „ is-style-default “ hinzugefügt.

Jetzt müssen Sie nur noch die CSS-Eigenschaften deklarieren. Öffnen Sie die Datei „editor.scss “ und ersetzen Sie die aktuellen Stile durch Folgendes:

 .wp-block-my-affiliate-plugin-my-affiliate-block { padding: 2px; &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Jetzt können Sie dasselbe mit style.scss tun :

 .wp-block-my-affiliate-plugin-my-affiliate-block { &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Stoppen Sie den Prozess (^C) und führen Sie npm run start erneut aus.

Und das ist es! Aktualisieren Sie die Seite und haben Sie Spaß mit Ihren neuen Blockstilen:

Verschachteln von Gutenberg-Blöcken mit der InnerBlocks-Komponente

Obwohl voll funktionsfähig, ist unser Affiliate-Block immer noch nicht sehr ansprechend. Um es für das Publikum ansprechender zu gestalten, könnten wir ein Bild hinzufügen.

Dies kann unserem Block eine Ebene der Komplexität hinzufügen, aber zum Glück müssen Sie das Rad nicht neu erfinden, da Gutenberg eine bestimmte Komponente bereitstellt, mit der Sie eine Struktur aus verschachtelten Blöcken erstellen können.

Die InnerBlocks Komponente ist wie folgt definiert:

InnerBlocks exportiert ein Komponentenpaar, das in Blockimplementierungen verwendet werden kann, um verschachtelte Blockinhalte zu ermöglichen.

Zuerst müssen Sie eine neue .js -Datei im src -Ordner erstellen. In unserem Beispiel nennen wir diese Datei container.js .

Jetzt müssen Sie die neue Ressource in die Datei index.js importieren :

 import './container';

Gehen Sie zurück zu container.js und importieren Sie die erforderlichen Komponenten:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor";

Der nächste Schritt besteht darin, eine Vorlage zu definieren, die die Struktur bereitstellt, in der die Blöcke platziert werden. Im folgenden Beispiel definieren wir eine Vorlage, die aus zwei Spalten besteht, die einen zentralen Bildblock und unseren benutzerdefinierten Affiliate-Block enthalten:

 const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ];

Die Vorlage ist als Array von blockTypes (Blockname und optionale Attribute) strukturiert.

Im obigen Code haben wir mehrere Attribute verwendet, um die Spalten und Spaltenblöcke zu konfigurieren. Insbesondere das Attribut templateLock: 'all' sperrt Spaltenblöcke, sodass der Benutzer vorhandene Blöcke nicht hinzufügen, neu anordnen oder löschen kann. templateLock kann einen der folgenden Werte annehmen:

• all – InnerBlocks ist gesperrt und es können keine Blöcke hinzugefügt, neu angeordnet oder entfernt werden.
• insert — Blöcke können nur neu angeordnet oder entfernt werden.
• false – Die Vorlage ist nicht gesperrt.

Die Vorlage wird dann dem InnerBlocks Element zugewiesen:

 <InnerBlocks template={ TEMPLATE } templateLock="all" />

Um Kompatibilitätsprobleme zu vermeiden, haben wir der InnerBlocks Komponente auch ein templateLock -Attribut hinzugefügt (siehe auch Issue #17262 und Pull #26128).

Hier ist unsere letzte container.js -Datei:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor"; const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ]; registerBlockType('my-affiliate-plugin/my-affiliate-container-block', { title: __( 'Container', 'my-affiliate-block' ), category: 'design', edit( { className } ) { return( <div className={ className }> <InnerBlocks template={ TEMPLATE } templateLock="all" /> </div> ) }, save() { const blockProps = useBlockProps.save(); return( <div { ...blockProps }> <InnerBlocks.Content /> </div> ) }, });

Zusätzliche Verbesserungen

Unser Block ist voll funktionsfähig, aber wir könnten ihn mit ein paar kleinen Änderungen noch etwas verbessern.

Wir haben das backgroundColor -Attribut dem von der RichText Komponente generierten Absatz zugewiesen. Wir können es jedoch vorziehen, die Hintergrundfarbe dem Container div zuzuweisen:

Ändern Sie also die Datei edit.js und save.js div s wie folgt:

 <div { ...blockProps } style={ { backgroundColor: backgroundColor } } > ... </div>

Dadurch kann der Benutzer den Hintergrund des gesamten Blocks ändern.

Andererseits betrifft eine relevantere Änderung die useBlockProps Methode. Im ursprünglichen Code haben wir die Konstante blockProps wie folgt definiert:

 const blockProps = useBlockProps();

Aber wir können die useBlockProps effektiver verwenden, indem wir eine Reihe von Eigenschaften übergeben. Beispielsweise können wir classnames aus dem classnames importieren und den Wrapper-Klassennamen entsprechend festlegen.

Im folgenden Beispiel weisen wir einen Klassennamen basierend auf dem Wert des align -Attributs ( edit.js ) zu:

 import classnames from 'classnames'; ... export default function Edit( { attributes, setAttributes } ) { ... const blockProps = useBlockProps( { className: classnames( { [ `has-text-align-${ align }` ]: align, } ) } ); ... }

Wir werden die gleiche Änderung in der save.js -Datei vornehmen:

 import classnames from 'classnames'; ... export default function save( { attributes } ) { ... const blockProps = useBlockProps.save({ className: classnames( { [ `has-text-align-${ align }` ]: align, } ) }); ... }

Und das ist ein Wrap! Sie können den Build jetzt für die Produktion ausführen.

Zusammenfassung

Und hier sind wir am Ende dieser unglaublichen Reise! Wir haben mit der Konfiguration der Entwicklungsumgebung begonnen und am Ende einen kompletten Blocktyp erstellt.

Wie wir in der Einleitung erwähnt haben, sind solide Kenntnisse in Node.js, Webpack, Babel und React unerlässlich, um fortgeschrittene Gutenberg-Blöcke zu erstellen und sich als professioneller Gutenberg-Entwickler auf dem Markt zu positionieren.

Aber Sie müssen keine React-Erfahrung haben, um Spaß an der Blockentwicklung zu haben. Die Blockentwicklung könnte Ihnen Motivation und Ziele geben, um immer breitere Kenntnisse in den Technologien hinter Gutenberg-Blöcken zu erwerben.

Dieser Leitfaden ist daher bei weitem nicht vollständig. Es ist lediglich eine Einführung in eine Vielzahl von Themen, die Ihnen helfen werden, mit dem Bau Ihrer allerersten Gutenberg-Blöcke zu beginnen.

Aus diesem Grund empfehlen wir Ihnen, Ihr Wissen zu vertiefen, indem Sie Online-Dokumentationen und Leitfäden sorgfältig lesen. Unter den vielen verfügbaren Ressourcen empfehlen wir die folgenden:

• Offizielles Tutorial zum Erstellen eines Blocks für Anfänger
• Offizielles Block-Tutorial für fortgeschrittene Entwickler
• Dynamische Blöcke
• Meta-Boxen
• Erstellen einer Seitenleiste für Ihr Plugin

Wenn Sie gerade erst mit der WordPress-Entwicklung beginnen, möchten Sie vielleicht die grundlegenden Konzepte der Frontend-Entwicklung verstehen. Hier ist eine kurze Liste von Ressourcen, die Ihnen beim Einstieg helfen können:

• So installieren Sie WordPress lokal (kostenloses E-Book)
• Der wahre Wert von Managed WordPress Hosting (kostenloses E-Book)
• Was ist JavaScript?
• HTML vs. HTML5
• So bearbeiten Sie CSS in WordPress
• Was ist PHP?
• Das WordPress Hooks Bootcamp: So verwenden Sie Aktionen, Filter und benutzerdefinierte Hooks

Und denken Sie daran, dass der vollständige Code der Beispiele dieses Handbuchs auf Gist verfügbar ist.

Jetzt bist du dran: Hast du irgendwelche Gutenberg-Blöcke entwickelt? Was sind die größten Schwierigkeiten, die Sie bisher erlebt haben? Teilen Sie uns Ihre Erfahrungen in den Kommentaren mit!