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:
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.
{
"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;
},
},
});
Så fungerar det:
data-wp-context='{ "isOpen": false }'skapar ett lokalt booleskt värde för den här instansen.- När du klickar på knappen anropas
actions.toggle, som växlarcontext.isOpen. data-wp-bind--hidden="!context.isOpen"döljer eller visar panelen.data-wp-bind--aria-expandedochdata-wp-textuppdaterar 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.
{
"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);
}
Det här är nytt:
getElement()returnerar{ ref }därrefär DOM-elementet. Vi läserdata-indexfö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ändercallbacks.isActiveTabför att kontrollera om deras index matcharcontext.activeTab.data-wp-class--is-active-tablägger till eller tar bort klassenis-active-tabutifrån återanropets returvärde.
Modal
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.
{
"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;
}
},
},
});
Det här är nytt:
data-wp-on-document--keydownlyssnar pådocumenti 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 anroparactions.stopPropagationför att hindra klick inuti dialogrutan från att stänga den. role="dialog"ocharia-modal="true"talar om för skärmläsare att det här är en modal dialogruta.aria-labelbinds så att det bara gäller när modalen är synlig.- Attributet
hiddenpå ö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.
{
"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;
}
Det här är nytt:
wp_interactivity_state()initierar antalet från PHP. Värdet serialiseras till sidans HTML och är tillgängligt somstate.counti direktiv och JavaScript.statejämfört medcontext: antalet finns istate(globalt, delat), medanlikedfinns icontext(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(): anropetstore()returnerar ett reaktivtstate-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:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<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
- Referens för interaktivitet: konfigurationsalternativ, detaljer om stöd i redigeraren och objektformen för inställningen
interactivity. - Tillgångar: hur Blockstudio laddar
script.js,style.cssoch andra blocktillgångar. - Dokumentation för WordPress Interactivity API: den fullständiga API-referensen, inklusive
data-wp-each,data-wp-init,data-wp-runoch andra direktiv som inte behandlas i den här guiden.