Hoppa till innehåll

Bygga interaktiva komponenter

WordPress-block är statiska som standard. Redigeraren sparar HTML i databasen, frontend återger det, och sedan är det klart. För många block är det precis rätt. Men vissa komponenter behöver reagera på användarinteraktion: växla innehåll, byta flikar, öppna dialogrutor och uppdatera räknare.

WordPress Interactivity API lägger till reaktivt beteende på klientsidan i block med hjälp av HTML-attribut som kallas direktiv. Du skriver data-wp-on--click i stället för addEventListener, data-wp-bind--hidden i stället för element.hidden = true. API hanterar reaktivitet, kontextisolering och hydrering automatiskt.

Blockstudio sköter kopplingarna. Ange "interactivity": true i din block.json så genererar Blockstudio importmappningen, läser in API i både redigeraren och frontend och löser dina ES-modulimporter. Inga byggsteg, ingen paketerare, ingen webpack-konfiguration. Se referensen för Interactivity för konfigurationsinformation.

Den här guiden går igenom fyra kompletta komponenter, där varje komponent introducerar nya begrepp. När du är klar har du fungerande mönster för de vanligaste interaktiva UI-elementen.

Så fungerar det

Direktiv

Direktiv är data-wp-*-attribut som deklarerar reaktivt beteende direkt i din HTML. De vanligaste:

Direktivet Syfte Exempel
data-wp-interactive Definiera namnrymden för lagret data-wp-interactive="myBlock"
data-wp-context Lokalt reaktivt tillstånd per instans data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Händelsehanterare data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Binda ett HTML-attribut data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Växla en CSS-klass data-wp-class--is-active="context.isActive"
data-wp-text Ange textinnehåll data-wp-text="state.count"
data-wp-style--[prop] Ange en infogad stil data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Global dokumenthändelse data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Köra återanrop när tillståndet ändras data-wp-watch="callbacks.log"
data-wp-each Loopa genom en array data-wp-each="state.items"

Lagret

Varje interaktivt block har ett lager, som skapas genom att anropa store() med en namnrymd och ett objekt som innehåller actions, callbacks och eventuellt state:

JavaScript
import { store, getContext } from '@wordpress/interactivity';

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

Inuti åtgärder returnerar getContext() det närmaste data-wp-context-objektet uppåt i DOM-trädet. getElement() returnerar en referens till DOM-elementet som utlöste åtgärden, vilket är användbart när du ska läsa data-*-attribut.

Kontext och tillstånd

Kontext (data-wp-context) är lokal för varje blockinstans. Om du placerar tre dragspel på en sida har vart och ett ett eget värde för isOpen. Om du växlar ett påverkas inte de andra.

Tillstånd (wp_interactivity_state()) är globalt och delas mellan alla instanser av ett block. Använd det för data som kommer från servern (som ett kommentarsantal) eller värden som ska vara desamma överallt.

Kontext fungerar både i redigeraren och på frontend. Tillstånd fungerar bara på frontend eftersom WordPress serialiserar det till en skripttagg som inte ingår i redigerarens REST API-svar.

Dragspel

Det enklaste interaktiva mönstret: klicka på en knapp och växla visningen av innehåll. Det här exemplet behöver bara tre direktiv och några rader 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;
    },
  },
});

Så fungerar det:

  1. data-wp-context='{ "isOpen": false }' skapar ett lokalt booleskt värde för den här instansen.
  2. När du klickar på knappen anropas actions.toggle, som växlar context.isOpen.
  3. data-wp-bind--hidden="!context.isOpen" döljer eller visar panelen.
  4. data-wp-bind--aria-expanded och data-wp-text uppdaterar knappens tillstånd för tillgänglighet och den visuella indikatorn.

Eftersom varje blockinstans får sin egen kontext fungerar det direkt att placera flera dragspel på en sida. De växlas oberoende av varandra.

Flikar

Flikar introducerar två nya begrepp: data-wp-class--* för att växla CSS-klasser och getElement() för att läsa dataattribut från elementet som utlöste en åtgärd.

Det här exemplet använder ett upprepningsfält så att redaktörer kan lägga till så många flikar de behöver.

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);
}

Det här är nytt:

  • getElement() returnerar { ref } där ref är DOM-elementet. Vi läser data-index för att ta reda på vilken flik som klickades på. Då behöver du inte skapa en separat åtgärd för varje flik.
  • callbacks är härledda värden som beräknas om när kontexten ändras. Både flikknapparna och panelerna använder callbacks.isActiveTab för att kontrollera om deras index matchar context.activeTab.
  • data-wp-class--is-active-tab lägger till eller tar bort klassen is-active-tab utifrån återanropets returvärde.

Modalen introducerar händelsehantering på dokumentnivå med data-wp-on-document--keydown för att stänga med Escape och stängning när du klickar på bakgrunden. Den visar också korrekta tillgänglighetsattribut för dialogrutor.

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;
      }
    },
  },
});

Det här är nytt:

  • data-wp-on-document--keydown lyssnar på document i stället för på själva elementet. Hanteraren körs oavsett vilket element som har fokus, så Escape fungerar var som helst.
  • Stängning vid klick på bakgrunden använder två lager: överlägget anropar actions.backdropClick, medan den inre dialogrutan anropar actions.stopPropagation för att hindra klick inuti dialogrutan från att stänga den.
  • role="dialog" och aria-modal="true" talar om för skärmläsare att det här är en modal dialogruta. aria-label binds så att det bara gäller när modalen är synlig.
  • Attributet hidden på överlägget döljer modalen och hindrar dokumentets keydown-lyssnare från att köras när modalen är stängd, eftersom direktiv på dolda element pausas.

Gilla-knapp med servertillstånd

Det här exemplet kombinerar tillstånd på serversidan med åtgärder på klientsidan. Antalet gilla-markeringar initieras från PHP med wp_interactivity_state(), och knappen uppdaterar det vid klick.

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;
}

Det här är nytt:

  • wp_interactivity_state() initierar antalet från PHP. Värdet serialiseras till sidans HTML och är tillgängligt som state.count i direktiv och JavaScript.
  • state jämfört med context: antalet finns i state (globalt, delat), medan liked finns i context (per instans). Om du hade flera gilla-knappar för samma objekt skulle de dela på antalet, men varje knapp kunde hålla reda på sin egen gillastatus.
  • Destrukturering från store(): anropet store() returnerar ett reaktivt state-objekt som du kan referera till i dina åtgärder.

Viktigt att tänka på: Servertillstånd fungerar bara på frontend. I redigeraren återges blocket via REST API, så wp_interactivity_state() inkluderas inte. Reservtexten som återges av PHP (<?php echo esc_html( $count ); ?>) visas som startvärde i redigerarens förhandsgranskning. Använd data-wp-context i stället om tillståndet ska vara interaktivt i redigeraren.

Tips och mönster

Namngivningskonventioner för namnrymder. Använd namnet på ditt tema eller tillägg som prefix: myTheme/accordion, myPlugin/tabs. Det förhindrar kollisioner när flera block på samma sida använder Interactivity API.

Inget byggsteg behövs. Blockstudio läser in script.js som en inbyggd ES-modul och genererar importmappningen för @wordpress/interactivity automatiskt. Du skriver vanlig JavaScript med import-satser, och det fungerar direkt.

Block med enbart direktiv. Om ditt block bara använder data-wp-context med data-wp-bind--hidden eller data-wp-text behöver du inte alls någon script.js. Interactivity API hanterar detta deklarativt. Dragexemplet ovan skulle kunna fungera utan JavaScript om du använde ett kryssrutetrick, men skriptlösningen är renare.

Felsökning med data-wp-watch. Lägg till ett watch-återanrop för att logga kontextändringar under utvecklingen:

JavaScript
store('myBlock', {
  callbacks: {
    debug: () => {
      const context = getContext();
      console.log('context changed:', { ...context });
    },
  },
});
HTML
<div data-wp-watch="callbacks.debug" ...>

Ta bort det innan du levererar.

Håll kontexten minimal. Lägg bara värden i data-wp-context som faktiskt ändras. Statiska data som etiketter och innehåll ska vara kvar i PHP. Kontexten JSON serialiseras till varje instans av blocket, så stora objekt gör sidan tyngre.

Nästa steg