Izdelava interaktivnih komponent
WordPress bloki so privzeto statični. Urejevalnik shrani HTML v zbirko podatkov, frontend pa jo izriše in s tem je zgodba končana. Pri številnih blokih je to povsem ustrezno. Nekatere komponente pa se morajo odzivati na uporabniške interakcije: preklapljanje vsebine, menjavanje zavihkov, odpiranje pogovornih oken in posodabljanje števcev.
WordPress Interactivity API doda blokom reaktivno delovanje na strani odjemalca z atributi HTML, imenovanimi direktive. Namesto addEventListener napišete data-wp-on--click, namesto element.hidden = true pa data-wp-bind--hidden. API samodejno poskrbi za reaktivnost, izolacijo konteksta in hidracijo.
Blockstudio poskrbi za povezovanje. Nastavite "interactivity": true v svojem block.json, Blockstudio pa ustvari importmap, naloži API v urejevalniku in na frontendu ter razreši vaše uvoze modulov ES. Brez koraka gradnje, povezovalnika ali konfiguracije webpacka. Podrobnosti o konfiguraciji najdete v referenci Interactivity.
Ta vodnik vas vodi skozi štiri celovite komponente, od katerih vsaka predstavi nove koncepte. Ob koncu boste poznali delujoče vzorce za najpogostejše interaktivne elemente UI.
Kako deluje
Direktive
Direktive so atributi data-wp-*, ki določajo reaktivno vedenje neposredno v vašem HTML. Najpogosteje uporabljene so:
| Direktiva | Namen | Primer |
|---|---|---|
data-wp-interactive |
Določi imenski prostor shrambe | data-wp-interactive="myBlock" |
data-wp-context |
Lokalno reaktivno stanje za vsak primerek | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Oskrbovalnik dogodka | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Poveži atribut HTML | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Preklopi razred CSS | data-wp-class--is-active="context.isActive" |
data-wp-text |
Nastavi besedilno vsebino | data-wp-text="state.count" |
data-wp-style--[prop] |
Nastavi vgrajeni slog | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Globalni dogodek dokumenta | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Zaženi povratni klic ob spremembi stanja | data-wp-watch="callbacks.log" |
data-wp-each |
Pojdi skozi polje | data-wp-each="state.items" |
Shramba
Vsak interaktivni blok ima shrambo, ki jo ustvarite s klicem store() z imenskim prostorom in objektom, ki vsebuje actions, callbacks in po želji state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Znotraj dejanj getContext() vrne najbližji objekt data-wp-context v drevesu DOM. getElement() vrne sklic na element DOM, ki je sprožil dejanje, kar je uporabno za branje atributov data-*.
Kontekst in stanje
Kontekst (data-wp-context) je lokalen za vsak primerek bloka. Če na stran postavite tri harmonike, ima vsak svojo vrednost isOpen. Preklop enega ne vpliva na druge.
Stanje (wp_interactivity_state()) je globalno in v skupni rabi med vsemi primerki bloka. Uporabite ga za podatke s strežnika (na primer število komentarjev) ali vrednosti, ki morajo biti povsod enake.
Kontekst deluje tako v urejevalniku kot na frontendu. Stanje je na voljo samo na frontendu, ker ga WordPress serializira v oznako skripta, ki ni vključena v odzive urejevalnika REST API.
Harmonika
Najpreprostejši interaktivni vzorec: kliknite gumb in preklopite prikaz vsebine. Ta primer potrebuje le tri direktive in nekaj vrstic 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;
},
},
});
Kako deluje:
data-wp-context='{ "isOpen": false }'ustvari lokalno logično vrednost za ta primerek.- Klik gumba pokliče
actions.toggle, ki preklopicontext.isOpen. data-wp-bind--hidden="!context.isOpen"skrije ali prikaže ploščo.data-wp-bind--aria-expandedindata-wp-textposodobita stanje gumba za dostopnost in vizualni indikator.
Ker vsak primerek bloka dobi svoj kontekst, lahko na stran brez dodatnih nastavitev postavite več harmonik. Preklapljajo se neodvisno.
Zavihki
Zavihki uvedejo dva nova koncepta: data-wp-class--* za preklapljanje razredov CSS in getElement() za branje podatkovnih atributov elementa, ki je sprožil dejanje.
Ta primer uporablja ponavljajoče se polje, da lahko uredniki dodajo poljubno število zavihkov.
{
"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);
}
Kaj je novega:
getElement()vrne{ ref }, kjer jerefelement DOM. Preberemodata-index, da ugotovimo, kateri zavihek je bil kliknjen. Tako ni treba ustvariti ločenega dejanja za vsak zavihek.callbacksso izpeljane vrednosti, ki se znova ovrednotijo ob spremembi konteksta. Gumbi zavihkov in plošče uporabljajocallbacks.isActiveTab, da preverijo, ali se njihov indeks ujema zcontext.activeTab.data-wp-class--is-active-tabdoda ali odstrani razredis-active-tabglede na vrednost, ki jo vrne povratni klic.
Modalno okno
Modalno okno uporablja obravnavo dogodkov na ravni dokumenta z data-wp-on-document--keydown za zapiranje s tipko Escape in zapiranje s klikom na ozadje. Prikazuje tudi pravilne atribute dostopnosti za pogovorno okno.
{
"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;
}
},
},
});
Kaj je novega:
data-wp-on-document--keydownposluša nadocumentnamesto na samem elementu. Oskrbovalnik se sproži ne glede na to, kateri element ima fokus, zato Escape deluje od koder koli.- Zapiranje s klikom na ozadje uporablja dve plasti: prekrivni element div pokliče
actions.backdropClick, notranje pogovorno okno pa pokličeactions.stopPropagation, da kliki znotraj njega ne povzročijo zapiranja. role="dialog"inaria-modal="true"bralnikom zaslona sporočita, da gre za modalno pogovorno okno.aria-labelje vezan tako, da velja samo, ko je modalno okno vidno.- Atribut
hiddenna prekrivnem elementu skrije modalno okno in prepreči sprožitev poslušalnika dogodkov keydown v dokumentu, ko je okno zaprto, saj so direktive na skritih elementih začasno ustavljene.
Gumb »Všeč mi je« s stanjem s strežnika
Ta primer združuje stanje na strani strežnika z dejanji na strani odjemalca. Število všečkov se inicializira iz PHP z uporabo wp_interactivity_state(), gumb pa ga posodobi ob kliku.
{
"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;
}
Kaj je novega:
wp_interactivity_state()inicializira število iz PHP. Vrednost se serializira v HTML strani in je v direktivah terstate.countna voljo kot JavaScript.statev primerjavi zcontext: število je vstate(globalno, v skupni rabi), medtem ko jelikedvcontext(za vsak primerek posebej). Če bi za isti element uporabili več gumbov »Všeč mi je«, bi si delili število, vsak pa bi lahko spremljal svoje stanje všečkanja.- Razčlenitev vrednosti iz
store(): klicstore()vrne reaktivni objektstate, na katerega se lahko sklicujete v dejanjih.
Pomembna omejitev: Stanje s strežnika je na voljo samo na frontendu. V urejevalniku se blok izriše prek REST API, zato wp_interactivity_state() ni vključeno. Nadomestno besedilo, izrisano z PHP (<?php echo esc_html( $count ); ?>), je prikazano kot začetna vrednost v predogledu urejevalnika. Za interaktivno stanje v urejevalniku uporabite data-wp-context.
Nasveti in vzorci
Dogovori o imenih. Kot predpono uporabite ime teme ali vtičnika: myTheme/accordion, myPlugin/tabs. Tako preprečite trke, kadar več blokov na isti strani uporablja API Interactivity.
Korak gradnje ni potreben. Blockstudio naloži script.js kot izvorni modul ES in samodejno ustvari importmap za @wordpress/interactivity. Pišete običajni JavaScript z ukazi import in vse deluje takoj.
Bloki samo z direktivami. Če vaš blok uporablja samo data-wp-context z data-wp-bind--hidden ali data-wp-text, datoteke script.js sploh ne potrebujete. Interactivity API to obravnava deklarativno. Zgornji primer harmonike bi lahko deloval brez JavaScript, če bi uporabili trik s potrditvenim poljem, vendar je pristop s skriptom čistejši.
Odpravljanje napak z data-wp-watch. Med razvojem dodajte povratni klic za spremljanje, da beležite spremembe konteksta:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Pred izdajo ga odstranite.
Kontekst naj bo čim manjši. V data-wp-context dodajte samo vrednosti, ki se dejansko spreminjajo. Statični podatki, kot so oznake in vsebina, naj ostanejo v PHP. Kontekst JSON se serializira v vsak primerek bloka, zato veliki objekti povečajo velikost strani.
Naslednji koraki
- Referenca Interactivity: možnosti konfiguracije, podrobnosti o podpori v urejevalniku in objektna oblika nastavitve
interactivity. - Sredstva: kako Blockstudio nalaga
script.js,style.cssin druga sredstva blokov. - WordPress dokumentacija za Interactivity API: celotna referenca za API, vključno z
data-wp-each,data-wp-init,data-wp-runin drugimi direktivami, ki v tem vodniku niso zajete.