Interaktive Komponenten erstellen
WordPress-Blöcke sind standardmäßig statisch. Der Editor speichert HTML in der Datenbank, das Frontend rendert es, und damit ist die Sache erledigt. Für viele Blöcke ist das genau richtig. Manche Komponenten müssen jedoch auf Interaktionen reagieren: Inhalte ein- und ausblenden, Tabs wechseln, Dialoge öffnen oder Zähler aktualisieren.
Die Interactivity WordPressAPI fügt Blöcken reaktives Verhalten auf der Clientseite hinzu. Dafür verwendet sie HTML-Attribute, sogenannte Direktiven. Du schreibst data-wp-on--click statt addEventListener und data-wp-bind--hidden statt element.hidden = true. Die API übernimmt Reaktivität, Kontextisolierung und Hydrierung automatisch.
Blockstudio übernimmt die Einrichtung. Setze "interactivity": true in deiner block.json, und Blockstudio erstellt die Importmap, lädt das API im Editor und im Frontend und löst deine ES-Modul-Imports auf. Kein Build-Schritt, kein Bundler und keine webpack-Konfiguration. Details zur Konfiguration findest du in der Interactivity-Referenz.
Dieser Leitfaden führt durch vier vollständige Komponenten, die jeweils neue Konzepte vorstellen. Am Ende hast du funktionierende Muster für die häufigsten interaktiven UI-Elemente.
So funktioniert es
Direktiven
Direktiven sind data-wp-*-Attribute, die reaktives Verhalten direkt in deinem HTML deklarieren. Die am häufigsten verwendeten sind:
| Direktive | Zweck | Beispiel |
|---|---|---|
data-wp-interactive |
Store-Namespace definieren | data-wp-interactive="myBlock" |
data-wp-context |
Lokaler reaktiver Zustand pro Instanz | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Ereignisbehandlung | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Ein HTML-Attribut binden | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Eine CSS-Klasse umschalten | data-wp-class--is-active="context.isActive" |
data-wp-text |
Textinhalt festlegen | data-wp-text="state.count" |
data-wp-style--[prop] |
Inline-Stil festlegen | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Globales Dokumentereignis | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Callback bei Zustandsänderung ausführen | data-wp-watch="callbacks.log" |
data-wp-each |
Ein Array durchlaufen | data-wp-each="state.items" |
Der Store
Jeder interaktive Block hat einen Store, der durch Aufruf von store() mit einem Namespace und einem Objekt mit actions, callbacks und optional state erstellt wird:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Innerhalb von Actions gibt getContext() das nächstgelegene data-wp-context-Objekt im DOM-Baum zurück. getElement() gibt eine Referenz auf das DOM-Element zurück, das die Action ausgelöst hat. Das ist nützlich, um data-*-Attribute auszulesen.
Kontext und Zustand
Kontext (data-wp-context) gilt nur für die jeweilige Blockinstanz. Wenn du drei Akkordeons auf einer Seite platzierst, hat jedes seinen eigenen Wert für isOpen. Wenn du eines umschaltest, bleiben die anderen unverändert.
Zustand (wp_interactivity_state()) ist global und wird von allen Instanzen eines Blocks gemeinsam genutzt. Verwende ihn für Daten vom Server, etwa die Anzahl der Kommentare, oder für Werte, die überall gleich sein sollen.
Kontext funktioniert sowohl im Editor als auch im Frontend. Der Zustand ist nur im Frontend verfügbar, weil WordPress ihn in einem Script-Tag serialisiert, das in den REST-API-Antworten des Editors nicht enthalten ist.
Akkordeon
Das einfachste interaktive Muster: Klicke auf einen Button und blende Inhalte ein oder aus. Dieses Beispiel benötigt nur drei Direktiven und wenige Zeilen JavaScript.
{
"name": "my-theme/accordion",
"title": "Accordion",
"category": "text",
"icon": "arrow-down-alt2",
"description": "Expandable content section.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "Accordion heading" },
{ "id": "body", "type": "textarea", "label": "Body", "default": "Accordion content goes here." }
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/accordion"
data-wp-context='{ "isOpen": false }'>
<button
data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen"
aria-controls="accordion-panel"
style="all: unset; cursor: pointer; display: flex; justify-content: space-between; align-items: center; width: 100%; padding: 1rem; font-weight: 600; font-size: 1.125rem;">
<?php echo esc_html( $a['heading'] ); ?>
<span aria-hidden="true" data-wp-text="context.isOpen ? '−' : '+'">+</span>
</button>
<div
id="accordion-panel"
role="region"
data-wp-bind--hidden="!context.isOpen"
style="padding: 0 1rem 1rem;">
<p><?php echo esc_html( $a['body'] ); ?></p>
</div>
</div>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/accordion', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
So funktioniert es:
data-wp-context='{ "isOpen": false }'erstellt einen lokalen booleschen Wert für diese Instanz.- Beim Klicken auf den Button wird
actions.toggleaufgerufen undcontext.isOpenumgeschaltet. data-wp-bind--hidden="!context.isOpen"blendet das Panel ein oder aus.data-wp-bind--aria-expandedunddata-wp-textaktualisieren den Zustand des Buttons für Barrierefreiheit und die visuelle Anzeige.
Da jede Blockinstanz ihren eigenen Kontext erhält, funktionieren mehrere Akkordeons auf einer Seite sofort. Sie lassen sich unabhängig voneinander umschalten.
Tabs
Tabs führen zwei neue Konzepte ein: data-wp-class--* zum Umschalten von CSS-Klassen und getElement() zum Auslesen von Datenattributen des Elements, das eine Action ausgelöst hat.
In diesem Beispiel kommt ein Repeater-Feld zum Einsatz, damit Redakteure beliebig viele Tabs hinzufügen können.
{
"name": "my-theme/tabs",
"title": "Tabs",
"category": "text",
"icon": "table-row-after",
"description": "Tabbed content switcher.",
"blockstudio": {
"interactivity": true,
"attributes": [
{
"id": "tabs",
"type": "repeater",
"label": "Tabs",
"min": 1,
"max": 8,
"attributes": [
{ "id": "label", "type": "text", "label": "Tab Label", "default": "Tab" },
{ "id": "content", "type": "textarea", "label": "Content", "default": "Tab content goes here." }
]
}
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/tabs"
data-wp-context='{ "activeTab": 0 }'>
<div role="tablist" style="display: flex; gap: 0; border-bottom: 2px solid #e5e7eb;">
<?php foreach ( $a['tabs'] as $i => $tab ) : ?>
<button
role="tab"
data-index="<?php echo esc_attr( $i ); ?>"
data-wp-on--click="actions.selectTab"
data-wp-class--is-active-tab="callbacks.isActiveTab"
data-wp-bind--aria-selected="callbacks.isActiveTab"
style="padding: 0.75rem 1.5rem; background: none; border: none; cursor: pointer; font-weight: 500; border-bottom: 2px solid transparent; margin-bottom: -2px;">
<?php echo esc_html( $tab['label'] ); ?>
</button>
<?php endforeach; ?>
</div>
<?php foreach ( $a['tabs'] as $i => $tab ) : ?>
<div
role="tabpanel"
data-index="<?php echo esc_attr( $i ); ?>"
data-wp-bind--hidden="!callbacks.isActiveTab"
style="padding: 1.5rem 0;">
<p><?php echo esc_html( $tab['content'] ); ?></p>
</div>
<?php endforeach; ?>
</div>
import { store, getContext, getElement } from '@wordpress/interactivity';
store('myTheme/tabs', {
actions: {
selectTab: () => {
const context = getContext();
const { ref } = getElement();
context.activeTab = parseInt(ref.dataset.index, 10);
},
},
callbacks: {
isActiveTab: () => {
const context = getContext();
const { ref } = getElement();
return context.activeTab === parseInt(ref.dataset.index, 10);
},
},
});
.is-active-tab {
border-bottom-color: currentColor !important;
color: var(--wp--preset--color--primary, #111);
}
Das ist neu:
getElement()gibt{ ref }zurück, wobeirefdas DOM-Element ist. Wir lesendata-indexaus, um zu erkennen, welcher Tab angeklickt wurde. So brauchst du keine separate Action für jeden Tab.callbackssind abgeleitete Werte, die bei einer Kontextänderung neu berechnet werden. Sowohl die Tab-Buttons als auch die Panels verwendencallbacks.isActiveTab, um zu prüfen, ob ihr Index mitcontext.activeTabübereinstimmt.data-wp-class--is-active-tabfügt dieis-active-tab-Klasse hinzu oder entfernt sie, je nach Rückgabewert des Callbacks.
Modal
Das Modal führt mit data-wp-on-document--keydown die Behandlung von Ereignissen auf Dokumentebene ein, um es mit Escape zu schließen. Außerdem zeigt es, wie sich ein Klick auf den Hintergrund zum Schließen nutzen lässt, und demonstriert die richtigen Barrierefreiheitsattribute für Dialoge.
{
"name": "my-theme/modal",
"title": "Modal",
"category": "text",
"icon": "external",
"description": "Button that opens a modal dialog.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "buttonText", "type": "text", "label": "Button Text", "default": "Open Modal" },
{ "id": "title", "type": "text", "label": "Modal Title", "default": "Modal Title" },
{ "id": "body", "type": "textarea", "label": "Modal Body", "default": "Modal content goes here." }
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/modal"
data-wp-context='{ "isOpen": false }'>
<button
data-wp-on--click="actions.open"
style="padding: 0.75rem 1.5rem; background: #111; color: #fff; border: none; border-radius: 6px; cursor: pointer; font-size: 1rem;">
<?php echo esc_html( $a['buttonText'] ); ?>
</button>
<div
data-wp-bind--hidden="!context.isOpen"
data-wp-on--click="actions.backdropClick"
data-wp-on-document--keydown="actions.onKeydown"
style="position: fixed; inset: 0; z-index: 9999; display: flex; align-items: center; justify-content: center; background: rgba(0,0,0,0.5);">
<div
role="dialog"
aria-modal="true"
data-wp-bind--aria-label="context.isOpen ? '<?php echo esc_attr( $a['title'] ); ?>' : false"
data-wp-on--click="actions.stopPropagation"
style="background: #fff; border-radius: 12px; padding: 2rem; max-width: 32rem; width: 100%; margin: 1rem; position: relative;">
<h2 style="margin: 0 0 1rem; font-size: 1.25rem;"><?php echo esc_html( $a['title'] ); ?></h2>
<p style="margin: 0 0 1.5rem; color: #555;"><?php echo esc_html( $a['body'] ); ?></p>
<button
data-wp-on--click="actions.close"
style="padding: 0.5rem 1rem; background: #f3f4f6; border: none; border-radius: 6px; cursor: pointer;">
Close
</button>
</div>
</div>
</div>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/modal', {
actions: {
open: () => {
const context = getContext();
context.isOpen = true;
},
close: () => {
const context = getContext();
context.isOpen = false;
},
backdropClick: () => {
const context = getContext();
context.isOpen = false;
},
stopPropagation: (event) => {
event.stopPropagation();
},
onKeydown: (event) => {
if (event.key === 'Escape') {
const context = getContext();
context.isOpen = false;
}
},
},
});
Das ist neu:
data-wp-on-document--keydownlauscht aufdocumentstatt auf dem Element selbst. Der Handler wird unabhängig davon ausgelöst, welches Element den Fokus hat. So funktioniert Escape überall.- Schließen per Klick auf den Hintergrund nutzt zwei Ebenen: Das Overlay-div ruft
actions.backdropClickauf, während der innere Dialogactions.stopPropagationaufruft, damit Klicks im Dialog ihn nicht schließen. role="dialog"undaria-modal="true"teilen Screenreadern mit, dass es sich um einen modalen Dialog handelt.aria-labelwird gebunden, sodass es nur gilt, wenn das Modal sichtbar ist.- Das Attribut
hiddenam Overlay blendet das Modal aus und verhindert zugleich, dass der Keydown-Listener des Dokuments ausgelöst wird, wenn das Modal geschlossen ist, da Direktiven auf ausgeblendeten Elementen pausiert werden.
Like-Button mit Serverzustand
Dieses Beispiel kombiniert serverseitigen Zustand mit clientseitigen Actions. Die Like-Anzahl wird mit wp_interactivity_state() aus PHP initialisiert und beim Klicken über den Button aktualisiert.
{
"name": "my-theme/like-button",
"title": "Like Button",
"category": "text",
"icon": "heart",
"description": "A like button with a count.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "itemId", "type": "text", "label": "Item ID", "default": "post-1" }
]
}
}
<?php
$item_id = $a['itemId'];
$count = (int) get_option( "likes_{$item_id}", 0 );
wp_interactivity_state( 'myTheme/likeButton', array(
'count' => $count,
) );
?>
<div useBlockProps
data-wp-interactive="myTheme/likeButton"
data-wp-context='{ "liked": false }'>
<button
data-wp-on--click="actions.like"
data-wp-class--is-liked="context.liked"
style="display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.5rem 1rem; border: 2px solid #e5e7eb; border-radius: 999px; background: none; cursor: pointer; font-size: 1rem; transition: all 0.2s;">
<span data-wp-text="context.liked ? '❤️' : '🤍'">🤍</span>
<span data-wp-text="state.count"><?php echo esc_html( $count ); ?></span>
</button>
</div>
import { store, getContext } from '@wordpress/interactivity';
const { state } = store('myTheme/likeButton', {
actions: {
like: () => {
const context = getContext();
if (context.liked) {
context.liked = false;
state.count--;
} else {
context.liked = true;
state.count++;
}
},
},
});
.is-liked {
border-color: #ef4444 !important;
background: #fef2f2 !important;
}
Das ist neu:
wp_interactivity_state()initialisiert die Anzahl mit PHP. Der Wert wird in HTML der Seite serialisiert und ist in Direktiven und JavaScript alsstate.countverfügbar.stateundcontext: Die Anzahl liegt instate(global, gemeinsam genutzt), währendlikedincontextliegt (pro Instanz). Gäbe es mehrere Like-Buttons für dasselbe Element, würden sie sich die Anzahl teilen, aber jeder könnte seinen eigenen Like-Status verwalten.- Destrukturierung aus
store(): Der Aufrufstore()gibt ein reaktivesstate-Objekt zurück, auf das du in deinen Actions verweisen kannst.
Wichtiger Hinweis: Der Serverzustand ist nur im Frontend verfügbar. Im Editor wird der Block über REST API gerendert, daher ist wp_interactivity_state() nicht enthalten. Der von PHP gerenderte Ersatztext (<?php echo esc_html( $count ); ?>) wird in der Editorvorschau als Anfangswert angezeigt. Für interaktiven Zustand im Editor verwendest du stattdessen data-wp-context.
Tipps und Muster
Namenskonventionen. Verwende den Namen deines Themes oder Plugins als Präfix: myTheme/accordion, myPlugin/tabs. So vermeidest du Konflikte, wenn mehrere Blöcke auf derselben Seite die Interactivity API verwenden.
Kein Build-Schritt erforderlich. Blockstudio lädt script.js als natives ES-Modul und erstellt automatisch die Importmap für @wordpress/interactivity. Du schreibst standardmäßiges JavaScript mit import-Anweisungen und kannst sofort loslegen.
Blöcke nur mit Direktiven. Wenn dein Block nur data-wp-context mit data-wp-bind--hidden oder data-wp-text verwendet, brauchst du überhaupt kein script.js. Die Interactivity API übernimmt das deklarativ. Das Akkordeonbeispiel oben könnte ohne JavaScript auskommen, wenn du einen Checkbox-Trick verwendest. Der Ansatz mit einem Script ist jedoch sauberer.
Debugging mit data-wp-watch. Füge einen Watch-Callback hinzu, um während der Entwicklung Kontextänderungen zu protokollieren:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Entferne ihn, bevor du das Projekt veröffentlichst.
Halte den Kontext minimal. Füge nur Werte zu data-wp-context hinzu, die sich tatsächlich ändern. Statische Daten wie Bezeichnungen und Inhalte sollten in PHP bleiben. Der Kontext JSON wird in jeder Instanz des Blocks serialisiert. Große Objekte erhöhen daher das Seitengewicht.
Nächste Schritte
- Interactivity-Referenz: Konfigurationsoptionen, Details zur Editorunterstützung und die Objektform der Einstellung
interactivity. - Assets: So lädt Blockstudio
script.js,style.cssund andere Block-Assets. - Interactivity-API von WordPress: die vollständige API-Referenz mit
data-wp-each,data-wp-init,data-wp-runund weiteren Direktiven, die in diesem Leitfaden nicht behandelt werden.