useBlockProps
Standardmäßig erstellt Gutenberg einen Wrapper um Blöcke, damit sie im Editor interaktiv sind. Bei manchen Blocktypen wie Containern oder Spalten kann das problematisch sein, da sich das Markup im Editor und im Frontend unterscheidet. Mit dem Hook useBlockProps kannst du ein Element innerhalb der Blockvorlage als Wurzelelement festlegen und so im Editor und Frontend gleiches Markup erzeugen.
Verwendung
Füge einfach das Attribut useBlockProps zum Wurzelelement deines Blocks hinzu.
<div useBlockProps class="my-class">
<!--
This element will be rendered
as the root element of your block
in Gutenberg.
-->
</div>
Blockstudio führt Klassen und Attribute aus dem Editor (z. B. Ausrichtungsklassen) automatisch mit den in den Blockvorlagen definierten Angaben zusammen. Dafür wird intern get_block_wrapper_attributes verwendet.
Der Filter blockstudio/blocks/components/use_block_props/render wird sowohl im Frontend als auch im Editor-Renderpfad auf den Wrapper angewendet. Klassen, die ein Theme oder eine Integration pro Instanz hinzufügt, erscheinen daher sowohl auf der Editor-Arbeitsfläche als auch im gespeicherten Frontend-Markup.
Ausgabe:
<div class="my-class wp-block-your-block-name alignright">
</div>
Hinweise
Links im Editor
Blockstudio verhindert die Linknavigation im Blockeditor, einschließlich
target="_blank", Klicks mit Zusatztasten, Klicks mit der mittleren Maustaste und Tastaturaktivierung.
Klickereignisse erreichen weiterhin Gutenberg, sodass gewöhnliche Klicks den Block auswählen.
RichText bleibt bearbeitbar. Dies gilt mit und ohne useBlockProps,
einschließlich eines Ankers als Stammelement des Blocks.
Frontend-Links und die Kontextmenübefehle des Browsers bleiben unverändert. Du musst weder Links aus Vorlagen entfernen noch eine Verzweigung anhand von $isEditor einbauen.
Wurzelelement
Da eine Blockvorlage nur ein Wurzelelement haben kann, muss sie bei Verwendung von useBlockProps ein einzelnes Wurzelelement enthalten. Das folgende Beispiel funktioniert zum Beispiel nicht; Gutenberg erstellt dann einen Wrapper um die Vorlage.
<div useBlockProps>
First root element.
</div>
<span>
Second root element.
</span>
Ebenso kann useBlockProps nur einmal pro Blockvorlage verwendet werden.
@-Zeichen
Blockstudio wandelt die Blockvorlage in gültigen React-Code in Gutenberg um. Dazu wird html-react-parser verwendet. Dadurch kann das Zeichen @ nicht in einem HTML-Attributnamen verwendet werden.
Bibliotheken wie Alpine.js verwenden die Zeichen @, um Direktiven für HTML-Elemente festzulegen.
<button useBlockProps @click="console.log('hi')">
Click me
</button>
In Gutenberg wird dieses Attribut @click aus dem Element entfernt. (Im Frontend funktioniert es natürlich weiterhin.)
Um dieses Problem zu umgehen, kannst du die alternative Syntax verwenden, die Alpine.js bereitstellt.
<button useBlockProps x-on:click="console.log('hi')">
Click me
</button>
Das funktioniert sowohl in Gutenberg als auch im Frontend.
Body-Klassen der Arbeitsfläche
Wenn assets.reset.enabled aktiv ist, kopiert Blockstudio auch die bereinigten Klassen, die der Filter body_class von WordPress zurückgibt, auf die Arbeitsfläche des Block-Editors. Dadurch funktionieren Theme-Selektoren wie .brand-a .site-card an beiden Stellen.
Filtere die endgültige Klassenliste, wenn der Editor eine kleinere Auswahl benötigt:
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
return array_values(array_diff($classes, ['logged-in']));
});
Dieser Filter steuert nur, welche Klassen auf die Arbeitsfläche des Editors kopiert werden. Die Body-Klassen im Frontend bleiben unverändert.