Zum Inhalt springen

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:

JavaScript
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.

JSON
{
  "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." }
    ]
  }
}
PHP
<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>
JavaScript
import { store, getContext } from '@wordpress/interactivity';

store('myTheme/accordion', {
  actions: {
    toggle: () => {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
});

So funktioniert es:

  1. data-wp-context='{ "isOpen": false }' erstellt einen lokalen booleschen Wert für diese Instanz.
  2. Beim Klicken auf den Button wird actions.toggle aufgerufen und context.isOpen umgeschaltet.
  3. data-wp-bind--hidden="!context.isOpen" blendet das Panel ein oder aus.
  4. data-wp-bind--aria-expanded und data-wp-text aktualisieren 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.

JSON
{
  "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." }
        ]
      }
    ]
  }
}
PHP
<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>
JavaScript
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);
    },
  },
});
CSS
.is-active-tab {
  border-bottom-color: currentColor !important;
  color: var(--wp--preset--color--primary, #111);
}

Das ist neu:

  • getElement() gibt { ref } zurück, wobei ref das DOM-Element ist. Wir lesen data-index aus, um zu erkennen, welcher Tab angeklickt wurde. So brauchst du keine separate Action für jeden Tab.
  • callbacks sind abgeleitete Werte, die bei einer Kontextänderung neu berechnet werden. Sowohl die Tab-Buttons als auch die Panels verwenden callbacks.isActiveTab, um zu prüfen, ob ihr Index mit context.activeTab übereinstimmt.
  • data-wp-class--is-active-tab fügt die is-active-tab-Klasse hinzu oder entfernt sie, je nach Rückgabewert des Callbacks.

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.

JSON
{
  "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." }
    ]
  }
}
PHP
<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>
JavaScript
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--keydown lauscht auf document statt 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.backdropClick auf, während der innere Dialog actions.stopPropagation aufruft, damit Klicks im Dialog ihn nicht schließen.
  • role="dialog" und aria-modal="true" teilen Screenreadern mit, dass es sich um einen modalen Dialog handelt. aria-label wird gebunden, sodass es nur gilt, wenn das Modal sichtbar ist.
  • Das Attribut hidden am 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.

JSON
{
  "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
<?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>
JavaScript
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++;
      }
    },
  },
});
CSS
.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 als state.count verfügbar.
  • state und context: Die Anzahl liegt in state (global, gemeinsam genutzt), während liked in context liegt (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 Aufruf store() gibt ein reaktives state-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:

JavaScript
store('myBlock', {
  callbacks: {
    debug: () => {
      const context = getContext();
      console.log('context changed:', { ...context });
    },
  },
});
HTML
<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.css und andere Block-Assets.
  • Interactivity-API von WordPress: die vollständige API-Referenz mit data-wp-each, data-wp-init, data-wp-run und weiteren Direktiven, die in diesem Leitfaden nicht behandelt werden.