So fügen Sie benutzerdefinierte Blockstile zu WordPress Gutenberg-Blöcken hinzu

Ein etwas weniger bekanntes Feature in Gutenberg ist die Option, verschiedene Stile für Blöcke einzurichten. Sie können beliebig viele verschiedene Stile für jeden Blocktyp registrieren, um demselben Block unterschiedliche Designs zu geben. Mögliche Stile für Blöcke werden als Abschnitt auf der rechten Seite des Editors angezeigt. Jeder Stil bekommt seine eigene Vorschau. Wenn Sie Stile korrekt handhaben, sollte der Wechsel zwischen Stilen das Design sowohl im Editor als auch im Frontend sofort aktualisieren.

Die WordPress- Dokumentation für diese Funktion ist derzeit nicht so vollständig und informativ, wie sie sein könnte. In diesem Beitrag werfen wir einen detaillierten Blick darauf, wie Sie Ihre benutzerdefinierten Blockstile hinzufügen können und wie Sie mit dem Stil für sie umgehen sollten.

Diese Funktion funktioniert so, dass immer dann, wenn Gutenberg feststellt, dass ein Blocktyp als mindestens ein Stil registriert ist, das Feld „Stile” automatisch auf der rechten Seite des Editors erscheint. Darin kann der Redakteur zwischen dem Standardstil oder einem beliebigen wählen Blockstil, der hinzugefügt wurde.

In früheren Versionen (zumindest vor WordPress 5.3) musste beim Registrieren eines benutzerdefinierten Stils auch der Standardstil („kein Stil”) registriert werden. Glücklicherweise wurde dies in den neuesten Versionen von WordPress behoben. Jetzt müssen Sie also nur noch Ihre benutzerdefinierten Stile registrieren, und WordPress fügt den Standardstil automatisch hinzu.

Sie können benutzerdefinierte Blockstile auf zwei Arten registrieren; mit PHP oder mit Javascript. Wir werden uns beide ansehen. Aber zuerst ein paar Aha’s zum Umgang mit deinen Styles.

Ein Hinweis zum Einreihen von Stilen für Gutenberg

Es kann einige Verwirrung darüber geben, wie und wo Sie Ihre Stile (CSS-Dateien) hinzufügen sollen. nur zum Editor, zum Frontend oder ein Stylesheet für beide. Einer der Hauptzwecke des Gutenberg-Editors besteht darin, sicherzustellen, dass Sie im Editor eine ordnungsgemäße Vorschau des Aussehens Ihres Beitragsinhalts anzeigen können. Es wird daher empfohlen, dass Sie sicherstellen, dass Ihre benutzerdefinierten Stile sowohl im Editor als auch im Frontend angewendet werden.

Wie Sie damit umgehen, hängt wirklich von Ihrem Projekt und dem vorhandenen Stylesheet-Setup ab. Wenn Sie ein komplettes Design entwickeln, fügen Sie wahrscheinlich bereits Block-Styling in Ihr Frontend-Stylesheet ein. Sie könnten erwägen, ein separates Stylesheet hinzuzufügen, das Sie nur für den Editor in die Warteschlange stellen. Dies kann jedoch schwierig zu verwalten sein, wenn Sie viele verschiedene Stile hinzufügen. Sie müssten Ihre Stile an zwei Stellen aktualisieren und sicherstellen, dass die Ergebnisse gleich sind. Die Lösung dafür wäre, ein Stylesheet zu behalten, das Sie sowohl für den Editor als auch für das Frontend einreihen. Aber dann müsste Ihr Frontend mindestens zwei separate Stylesheets laden, und das ist möglicherweise nicht ideal.

Eine andere Lösung besteht darin, zB SCSS oder LESS zu verwenden und so einzurichten @imports, dass Sie Ihre Blockstile nur einmal schreiben müssen, und sie werden sowohl auf den Editor als auch auf das Frontend angewendet. Wie Sie unten sehen werden, haben Sie bei der Verwendung von PHP zur Registrierung benutzerdefinierter Blockstile noch eine weitere Option; um Inline-Stile hinzuzufügen. Diese Stile werden sowohl im Editor als auch im Frontend angewendet. Im Frontend werden sie von WordPress als benutzerdefinierte Inline <style type="text/css">...</style>im Header hinzugefügt.

Wie auch immer Sie es lösen möchten, wissen Sie, dass es ein paar neue Hooks für Registerstile (und Skripte) für Gutenberg gibt. Wenn Sie ein Stylesheet sowohl für das Frontend als auch für den Editor in die Warteschlange stellen möchten, verwenden Sie den Hook enqueue_block_assets. Wenn Sie ein Stylesheet nur für den Editor hinzufügen möchten, stellen Sie es in den Hook ein enqueue_block_editor_assets.

So wenden Sie Stile auf die benutzerdefinierten Blockstile an

Benutzerdefinierte Blockstile werden als Klasse eines bestimmten Musters zum äußersten HTML-Tag für den Block hinzugefügt.

Die CSS-Klasse für Blockstile wird in Form von „ is-style-<stylename>” hinzugefügt. Wenn Sie beispielsweise Ihren Stil „ outline” nennen, erhält der Block die Klasse „ is-style-outline“.

Es kann jedoch vorkommen, dass der Gutenberg-Editor in einigen Fällen Ihr Styling überschreibt. Ich empfehle, Ihrem Editor-Styling den Selektor voranzustellen editor-styles-wrapper, um sicherzustellen, dass Ihre Styles „gewinnen”. Denken Sie daran, dass diese Klasse im Frontend nicht vorhanden ist. Um sicherzugehen, müssen Sie möglicherweise zwei Selektoren wie folgt hinzufügen (wenn Sie dasselbe Stylesheet für Editor und Frontend verwenden):

.is-style-colored-bottom-border, 
.editor-styles-wrapper .is-style-colored-bottom-border { 
    border-bottom: 2px solid purple;
}

Hinzufügen benutzerdefinierter Blockstile mit PHP

Um einen benutzerdefinierten Blocktyp mit PHP hinzuzufügen, verwenden wir die Funktion [register_block_style](https://developer.wordpress.org/reference/functions/register_block_style/)(). In der Dokumentation fehlen leider Angaben, welchen Hook wir verwenden sollen, aber ich hatte Glück mit dem Hook init.

Sie müssen den Gutenberg-Namespace-Namen Ihres Blocktyps kennen, um ihm einen benutzerdefinierten Stil hinzuzufügen. Alle standardmäßigen WordPress-Blöcke haben den Namespace „ core“, gefolgt von einem /und einer Slug-Version ihres Namens. Zum Beispiel ist Gutenbergs Name für den Standard-Absatzblock core/paragraph.

Das Registrieren eines benutzerdefinierten Blockstils erfolgt in seiner einfachsten Form wie folgt:

Der obige Code fügt dem Heading-Blocktyp einen benutzerdefinierten Blockstil hinzu, was dazu führen würde, dass die Klasse is-style-colored-bottom-borderfür jede Überschrift verwendet wird, die diesen Stil ausgewählt hat.

Diese Funktion bietet Ihnen zwei Methoden zum Hinzufügen Ihres CSS (falls Sie es nicht auf andere Weise hinzugefügt haben); Entweder durch Bereitstellen von Inline-CSS als Zeichenfolge oder Bereitstellen eines registrierten Stylesheet-Handles, das WordPress bei Bedarf für Sie einreiht.

Wenn Sie Inline-Styling hinzufügen möchten (denken Sie daran, dass dies sowohl den Editor als auch das Frontend betrifft), fügen Sie das Element „ inline_style” zum Funktionsaufruf hinzu und schreiben Sie das vollständige CSS als Zeichenfolge als Wert aus:

Wenn Sie die Funktion lieber in ein Stylesheet einreihen möchten, geben Sie ihr Handle für das Element „ style_handle” an.

Passen Sie den Speicherort Ihres Stylesheets an Ihr Projekt an. Das Stylesheet wird sowohl auf den Editor als auch auf das Frontend angewendet, aber dieses Mal wird das Frontend eine separate Anfrage stellen, um dieses Stylesheet aufzunehmen. Diese Methode wird nicht empfohlen, wenn Sie mehrere Blockstile hinzufügen. Das Frontend wird durch das Anfordern einer ganzen Reihe separater Stylesheets erheblich verlangsamt.

Hinzufügen benutzerdefinierter Blockstile mit Javascript

Wenn Sie Ihre Blockstile lieber mit Javascript hinzufügen möchten, ist dies genauso einfach wie mit PHP.

Sie müssen eine Javascript-Datei nur in den Editor-Hook einreihen: enqueue_block_editor_assets. Ihr Skript wird wahrscheinlich keine Abhängigkeiten benötigen, aber ich ziehe es vor, mindestens ‘ wp-blocks‘ als Abhängigkeit hinzuzufügen.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script(
        'myguten-script', 
        get_template_directory_uri(). '/assets/js/myguten.js', 
        ['wp-blocks']
    );
});

Passen Sie den Dateinamen und den Speicherort an Ihr Projekt an.

In Ihrer Javascript-Datei verwenden Sie die Funktion registerBlockStyle()innerhalb des wp.blocksObjekts, um benutzerdefinierte Blockstile zu registrieren. Das Hinzufügen des gleichen Blockstils wie in PHP oben würde folgendermaßen aussehen:

wp.blocks.registerBlockStyle('core/heading', {
    name: 'colored-bottom-border',
    label: 'Colored bottom border'
});

Und das ist es! Kinderleicht.

Registrierung von Blockstilen aufheben

So wie Sie einen Blockstil registrieren können, kann ein Blockstil auch deregistriert werden. Vielleicht möchten Sie einige der Standard-Blockstile von WordPress entfernen? Wie beim Registrieren von Blockstilen können Sie Blockstile auch mit PHP oder Javascript abmelden. Aber die Wahl zwischen diesen beiden Methoden ist keine Präferenz mehr.

Sie können einen Block nicht bei PHP abmelden, wenn er bei Javascript registriert war, und umgekehrt. Sie müssen also herausfinden, wie der Stil, den Sie entfernen möchten, registriert wurde, und diesen entweder mit PHP oder Javascript abgleichen. Ich glaube, dass alle Blockstile von WordPress mit Javascript hinzugefügt werden (zitieren Sie mich nicht dazu!). Wenn Sie also einige davon entfernen möchten, müssen Sie den Javascript-Weg gehen.

Das Aufheben der Registrierung eines Blockstils bei PHP erfolgt durch Aufrufen der Funktion unregister_block_style(), wobei der Blocktyp und der Stilname angegeben werden, den Sie entfernen möchten. Das Aufheben der Registrierung des oben in diesem Beitrag hinzugefügten Stils (vorausgesetzt, er wurde mit PHP registriert) würde beispielsweise so aussehen:

add_action('init', function() {
    unregister_block_style('core/heading', 'colored-bottom-border');
});

Das Abmelden eines Blockstils mit Javascript erfolgt ähnlich wie bei der Funktion unregisterBlockStyle()innerhalb des wp.blocksObjekts. Bei Javascript ist es jedoch eine Frage, welches Skript zuerst ausgeführt wird, und es können Probleme auftreten, wenn Ihr Skript vor der Registrierung ausgeführt wird. Um dies zu lösen, verwenden wir Gutenbergs Äquivalent zu jQuerys „document ready” (jQuery(document).ready(function() { ... });) und fügen Ihrem Skript außerdem eine weitere Abhängigkeit hinzu.

Beginnen wir mit dem Hinzufügen einer neuen Skriptabhängigkeit zu Ihrer Javascript-Datei, die sich in die Warteschlange „ wp-edit-post” einreiht:

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script(
        'myguten-script', 
        get_template_directory_uri(). '/assets/js/myguten.js', 
        ['wp-blocks', 'wp-edit-post']
    );
});

Und packen Sie in Ihrer Javascript-Datei Ihren Unregister-Funktionsaufruf wp.domReady(function() { ... })wie folgt ein:

wp.domReady(function() {
    wp.blocks.unregisterBlockStyle('core/quote', 'large');
});

Wie der obige Code zeigt, können wir jetzt mit Javascript den „Large”-Stil von WordPress aus dem Quote-Block entfernen. Wenn Sie dasselbe mit PHP versuchen würden, würde es nicht funktionieren.

Eine Randnotiz zum Aufheben der Registrierung von Blockstilen

Möglicherweise stellen Sie fest, dass das Feld „Stile” im Editor nicht verschwindet, obwohl Sie alle benutzerdefinierten Blockstile erfolgreich von einem Block entfernt haben. Es bleibt dort, wo es nur die Auswahl „Standard” enthält. Wenn Sie das Feld „Stile” vollständig entfernen möchten, um die Redakteure nicht zu verwirren, können Sie auch einfach den Standardstil abmelden (z. B. wp.blocks.unregisterBlockStyle('core/quote', 'large')). Dadurch wird das Feld „Stile” vollständig aus dem Gutenberg-Editor entfernt.