Opbygning af interaktive komponenter
WordPress-blokke er statiske som standard. Editor gemmer HTML i databasen, frontend viser det, og så er historien slut. For mange blokke er det helt rigtigt. Men nogle komponenter skal reagere på brugerinteraktion: skifte visning af indhold, skifte faner, åbne dialoger, opdatere tællere.
WordPress Interactivity API tilføjer reaktiv adfærd på klientsiden til blokke ved hjælp af HTML-attributter kaldet direktiver. Du skriver data-wp-on--click i stedet for addEventListener, data-wp-bind--hidden i stedet for element.hidden = true. API håndterer automatisk reaktivitet, kontekstisolering og hydrering.
Blockstudio klarer forbindelserne. Angiv "interactivity": true i din block.json, så genererer Blockstudio importmap, indlæser API i både editoren og frontend og løser dine ES-modulimporter. Intet build-trin, ingen bundler, ingen webpack-konfiguration. Se referencen til Interactivity for konfigurationsoplysninger.
Denne vejledning gennemgår fire komplette komponenter, som hver introducerer nye begreber. Når du er færdig, har du fungerende mønstre for de mest almindelige interaktive UI-elementer.
Sådan fungerer det
Direktiver
Direktiver er data-wp-*-attributter, der angiver reaktiv adfærd direkte i din HTML. De mest anvendte er:
| Direktiv | Formål | Eksempel |
|---|---|---|
data-wp-interactive |
Definer navnerummet for store | data-wp-interactive="myBlock" |
data-wp-context |
Lokal reaktiv tilstand pr. instans | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Hændelseshåndtering | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Bind en HTML-attribut | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Slå en CSS-klasse til eller fra | data-wp-class--is-active="context.isActive" |
data-wp-text |
Angiv tekstindhold | data-wp-text="state.count" |
data-wp-style--[prop] |
Angiv en inline-typografi | 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ør callback, når tilstanden ændres | data-wp-watch="callbacks.log" |
data-wp-each |
Gennemløb et array | data-wp-each="state.items" |
Store
Hver interaktiv blok har en store, der oprettes ved at kalde store() med et navnerum og et objekt, der indeholder actions, callbacks og eventuelt state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
I actions returnerer getContext() det nærmeste data-wp-context-objekt op gennem DOM-træet. getElement() returnerer en reference til det DOM-element, der udløste handlingen, hvilket er nyttigt til at læse data-*-attributter.
Kontekst kontra tilstand
Kontekst (data-wp-context) er lokal for hver blokinstans. Hvis du placerer tre harmonikaer på en side, har hver sin egen værdi for isOpen. Når du slår én til eller fra, påvirker det ikke de andre.
Tilstand (wp_interactivity_state()) er global og deles mellem alle instanser af en blok. Brug den til data fra serveren (som et antal kommentarer) eller værdier, der skal være ens overalt.
Kontekst fungerer både i editoren og på frontend. Tilstand findes kun på frontend, fordi WordPress serialiserer den i et script-tag, som ikke er med i editorens REST API-svar.
Harmonika
Det enkleste interaktive mønster: Klik på en knap, og skift visningen af indhold. Dette eksempel kræver kun tre direktiver og nogle få linjer 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ådan fungerer det:
data-wp-context='{ "isOpen": false }'opretter en lokal boolesk værdi for denne instans.- Når der klikkes på knappen, kaldes
actions.toggle, som ændrercontext.isOpen. data-wp-bind--hidden="!context.isOpen"skjuler eller viser panelet.data-wp-bind--aria-expandedogdata-wp-textopdaterer knappens tilstand af hensyn til tilgængelighed og den visuelle indikator.
Da hver blokinstans får sin egen kontekst, fungerer det straks at placere flere harmonikaer på en side. De skifter visning uafhængigt af hinanden.
Faner
Faner introducerer to nye begreber: data-wp-class--* til at slå CSS-klasser til og fra og getElement() til at læse dataattributter fra det element, der udløste en handling.
Dette eksempel bruger et gentagelsesfelt, så redaktører kan tilføje så mange faner, de har brug for.
{
"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);
}
Hvad er nyt her:
getElement()returnerer{ ref }, hvorrefer DOM-elementet. Vi læserdata-indexfor at finde ud af, hvilken fane der blev klikket på. Så behøver vi ikke oprette en separat handling for hver fane.callbackser afledte værdier, der genberegnes, når konteksten ændres. Både faneknapperne og panelerne brugercallbacks.isActiveTabtil at kontrollere, om deres indeks stemmer overens medcontext.activeTab.data-wp-class--is-active-tabtilføjer eller fjerner klassenis-active-tabbaseret på callbackens returværdi.
Modal
Modalen introducerer hændelseshåndtering på dokumentniveau med data-wp-on-document--keydown til at lukke med Escape og lukning ved klik på baggrunden. Den viser også korrekte attributter for dialogtilgængelighed.
{
"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;
}
},
},
});
Hvad er nyt her:
data-wp-on-document--keydownlytter pådocumenti stedet for selve elementet. Håndteringen udløses, uanset hvilket element der har fokus, så Escape virker overalt.- Lukning ved klik på baggrunden bruger to lag: overlay-div-elementet kalder
actions.backdropClick, mens den indre dialog kalderactions.stopPropagationfor at forhindre, at klik i dialogen lukker den. role="dialog"ogaria-modal="true"fortæller skærmlæsere, at dette er en modal dialog.aria-labeler bundet, så den kun gælder, når modalen er synlig.- Attributten
hiddenpå overlayet skjuler både modalen og forhindrer, at dokumentets keydown-lytter udløses, når modalen er lukket, fordi direktiver på skjulte elementer sættes på pause.
Like-knap med servertiIstand
Dette eksempel kombinerer tilstand på serversiden med handlinger på klientsiden. Antallet af likes initialiseres fra PHP med wp_interactivity_state(), og knappen opdaterer det ved klik.
{
"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;
}
Hvad er nyt her:
wp_interactivity_state()initialiserer antallet fra PHP. Værdien serialiseres i sidens HTML og er tilgængelig somstate.counti direktiver og JavaScript.statekontracontext: Antallet ligger istate(globalt, delt), menslikedligger icontext(pr. instans). Hvis du havde flere like-knapper for samme element, ville de dele antallet, men hver kunne holde styr på sin egen likede-status.- Udpakning fra
store(): Kaldetstore()returnerer et reaktivtstate-objekt, som du kan henvise til i dine handlinger.
Vigtig begrænsning: ServertiIstand findes kun på frontend. I editoren vises blokken via REST API, så wp_interactivity_state() er ikke inkluderet. Reserveteksten fra PHP (<?php echo esc_html( $count ); ?>) vises som startværdi i editorens forhåndsvisning. Brug data-wp-context i stedet til tilstand, der kan interageres med i editoren.
Tips og mønstre
Konventioner for navnerum. Brug dit tema- eller pluginnavn som præfiks: myTheme/accordion, myPlugin/tabs. Det forhindrer sammenfald, når flere blokke på samme side bruger Interactivity API.
Intet build-trin påkrævet. Blockstudio indlæser script.js som et indbygget ES-modul og genererer automatisk importmap for @wordpress/interactivity. Du skriver standard-JavaScript med import-sætninger, og det virker med det samme.
Blokke med kun direktiver. Hvis din blok kun bruger data-wp-context med data-wp-bind--hidden eller data-wp-text, behøver du slet ikke en script.js. Interactivity API håndterer dette deklarativt. Harmonikaeksemplet ovenfor kan fungere uden JavaScript med et checkbox-trick, men scriptmetoden er renere.
Fejlfinding med data-wp-watch. Tilføj en watch-callback for at logge kontekstændringer under udvikling:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Fjern den, inden du sender produktet ud.
Hold konteksten minimal. Anbring kun værdier i data-wp-context, som faktisk ændrer sig. Statiske data som etiketter og indhold bør forblive i PHP. Kontekst-JSON serialiseres i hver blokinstans, så store objekter gør siden tungere.
Næste trin
- Reference til Interactivity: konfigurationsmuligheder, oplysninger om understøttelse i editoren og objektformen for indstillingen
interactivity. - Aktiver: sådan indlæser Blockstudio
script.js,style.cssog andre blokaktiver. - WordPress Interactivity-dokumentationAPI: den fulde reference til API, herunder
data-wp-each,data-wp-init,data-wp-runog andre direktiver, der ikke er dækket i denne vejledning.