Tvorba interaktívnych komponentov
Bloky WordPress sú predvolene statické. Editor ukladá HTML do databázy, frontend ho vykreslí a tým sa príbeh končí. Pri mnohých blokoch je to presne tak, ako má byť. Niektoré komponenty však musia reagovať na interakciu používateľa: prepínať obsah, meniť karty, otvárať dialógy či aktualizovať počítadlá.
WordPress Interactivity API pridáva blokom reaktívne správanie na strane klienta pomocou atribútov HTML nazývaných direktívy. Namiesto addEventListener píšete data-wp-on--click a namiesto element.hidden = true píšete data-wp-bind--hidden. API sa automaticky postará o reaktivitu, izoláciu kontextu a hydratáciu.
Blockstudio zabezpečuje prepojenie. Nastavte "interactivity": true vo svojom block.json a Blockstudio vygeneruje importmap, načíta API v editore aj na frontende a vyrieši importy modulov ES. Bez zostavovania, bez bundlera, bez konfigurácie webpacku. Podrobnosti o konfigurácii nájdete v referencii Interactivity.
Táto príručka vás prevedie štyrmi kompletnými komponentmi, z ktorých každý predstavuje nové koncepty. Na konci budete mať funkčné vzory pre najbežnejšie interaktívne prvky UI.
Ako to funguje
Direktívy
Direktívy sú atribúty data-wp-*, ktoré deklarujú reaktívne správanie priamo vo vašom HTML. Najčastejšie používané:
| Direktíva | Účel | Príklad |
|---|---|---|
data-wp-interactive |
Definuje menný priestor úložiska | data-wp-interactive="myBlock" |
data-wp-context |
Lokálny reaktívny stav pre každú inštanciu | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Obsluha udalosti | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Naviaže atribút HTML | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Prepína triedu CSS | data-wp-class--is-active="context.isActive" |
data-wp-text |
Nastaví textový obsah | data-wp-text="state.count" |
data-wp-style--[prop] |
Nastaví vnorený štýl | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Globálna udalosť dokumentu | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Spustí spätné volanie pri zmene stavu | data-wp-watch="callbacks.log" |
data-wp-each |
Prechádza prvky poľa | data-wp-each="state.items" |
Úložisko
Každý interaktívny blok má úložisko, ktoré vytvoríte zavolaním store() s menným priestorom a objektom obsahujúcim actions, callbacks a prípadne state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
V akciách funkcia getContext() vráti najbližší objekt data-wp-context v strome DOM. Funkcia getElement() vráti odkaz na prvok DOM, ktorý akciu vyvolal, čo je užitočné pri čítaní atribútov data-*.
Kontext a stav
Kontext (data-wp-context) je lokálny pre každú inštanciu bloku. Ak na stránku umiestnite tri akordeóny, každý má vlastnú hodnotu isOpen. Prepnutie jedného neovplyvní ostatné.
Stav (wp_interactivity_state()) je globálny a zdieľa sa medzi všetkými inštanciami bloku. Použite ho pre údaje zo servera, napríklad počet komentárov, alebo pre hodnoty, ktoré majú byť všade rovnaké.
Kontext funguje v editore aj na frontende. Stav je dostupný iba na frontende, pretože WordPress ho serializuje do značky script, ktorá nie je súčasťou odpovedí REST API editora.
Akordeón
Najjednoduchší interaktívny vzor: kliknete na tlačidlo a prepnete obsah. Tento príklad potrebuje iba tri direktívy a niekoľko riadkov 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;
},
},
});
Ako to funguje:
data-wp-context='{ "isOpen": false }'vytvorí pre túto inštanciu lokálnu logickú hodnotu.- Kliknutie na tlačidlo zavolá
actions.toggle, ktoré prepne hodnotucontext.isOpen. data-wp-bind--hidden="!context.isOpen"skryje alebo zobrazí panel.data-wp-bind--aria-expandedadata-wp-textaktualizujú stav tlačidla pre prístupnosť aj vizuálny indikátor.
Keďže každá inštancia bloku má vlastný kontext, na stránke môžete bez ďalšieho nastavovania umiestniť viac akordeónov. Prepínajú sa nezávisle.
Karty
Karty predstavujú dva nové koncepty: data-wp-class--* na prepínanie tried CSS a getElement() na čítanie dátových atribútov prvku, ktorý vyvolal akciu.
Tento príklad používa opakovacie pole, aby mohli editori pridať ľubovoľný počet kariet.
{
"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);
}
Čo je tu nové:
getElement()vráti{ ref }, v ktoromrefoznačuje prvok DOM. Hodnotudata-indexčítame, aby sme zistili, na ktorú kartu sa kliklo. Vďaka tomu netreba vytvárať samostatnú akciu pre každú kartu.callbackssú odvodené hodnoty, ktoré sa prepočítajú pri zmene kontextu. Tlačidlá kariet aj panely používajúcallbacks.isActiveTabna kontrolu, či sa ich index zhoduje scontext.activeTab.data-wp-class--is-active-tabpridáva alebo odstraňuje trieduis-active-tabpodľa návratovej hodnoty spätného volania.
Modálne okno
Modálne okno predstavuje obsluhu udalostí na úrovni dokumentu pomocou data-wp-on-document--keydown, ktoré ho zatvorí po stlačení Escape, a zatvorenie kliknutím na pozadie. Ukazuje tiež správne atribúty prístupnosti dialógu.
{
"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;
}
},
},
});
Čo je tu nové:
data-wp-on-document--keydownpočúva nadocumentnamiesto samotného prvku. Obsluha sa spustí bez ohľadu na to, ktorý prvok má zameranie, takže Escape funguje odkiaľkoľvek.- Zatvorenie kliknutím na pozadie používa dve vrstvy: prekryvný prvok div zavolá
actions.backdropClick, zatiaľ čo vnútorný dialóg zavoláactions.stopPropagation, aby zabránil zatvoreniu pri kliknutí dovnútra dialógu. role="dialog"aaria-modal="true"oznamujú čítačkám obrazovky, že ide o modálny dialóg.aria-labelje naviazaný tak, aby sa uplatnil iba vtedy, keď je modálne okno viditeľné.- Atribút
hiddenna prekryvnom prvku modálne okno skryje a zároveň zabráni spusteniu poslucháča udalosti keydown dokumentu, keď je okno zatvorené, pretože direktívy na skrytých prvkoch sú pozastavené.
Tlačidlo Páči sa mi to so stavom zo servera
Tento príklad kombinuje stav na strane servera s akciami na strane klienta. Počet označení Páči sa mi to sa inicializuje z PHP pomocou wp_interactivity_state() a tlačidlo ho aktualizuje po kliknutí.
{
"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;
}
Čo je tu nové:
wp_interactivity_state()inicializuje počet z PHP. Hodnota sa serializuje do HTML stránky a v direktívach a JavaScript je dostupná akostate.count.stateacontext: počet je vstate(globálny, zdieľaný), zatiaľ čolikedje vcontext(pre každú inštanciu zvlášť). Ak by ste mali viac tlačidiel Páči sa mi to pre tú istú položku, zdieľali by počet, ale každé by mohlo sledovať vlastný stav označenia Páči sa mi to.- Rozbalenie z
store(): volaniestore()vráti reaktívny objektstate, na ktorý sa môžete odkazovať vo svojich akciách.
Dôležité upozornenie: Stav zo servera je dostupný iba na frontende. V editore sa blok vykresľuje prostredníctvom REST API, takže wp_interactivity_state() nie je zahrnutý. Náhradný text vykreslený pomocou PHP (<?php echo esc_html( $count ); ?>) sa v náhľade editora zobrazí ako počiatočná hodnota. Ak chcete interaktívny stav editora, použite namiesto toho data-wp-context.
Tipy a vzory
Konvencie pre menné priestory. Ako predponu použite názov témy alebo pluginu: myTheme/accordion, myPlugin/tabs. Predídete tak kolíziám, keď viacero blokov na tej istej stránke používa Interactivity API.
Zostavovanie nie je potrebné. Blockstudio načíta script.js ako natívny modul ES a automaticky vygeneruje importmap pre @wordpress/interactivity. Píšete štandardný JavaScript s príkazmi import a funguje to okamžite.
Bloky používajúce iba direktívy. Ak váš blok používa iba data-wp-context s data-wp-bind--hidden alebo data-wp-text, vôbec nepotrebujete script.js. Interactivity API ich spracuje deklaratívne. Vyššie uvedený príklad akordeónu by fungoval aj bez JavaScript, ak by ste použili trik s zaškrtávacím políčkom, no prístup so skriptom je prehľadnejší.
Ladenie pomocou data-wp-watch. Počas vývoja pridajte spätné volanie watch, ktoré bude zaznamenávať zmeny kontextu:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Pred nasadením ho odstráňte.
Kontext udržiavajte stručný. Do data-wp-context vkladajte iba hodnoty, ktoré sa skutočne menia. Statické údaje, ako sú označenia a obsah, ponechajte v PHP. Kontext JSON sa serializuje do každej inštancie bloku, takže veľké objekty zväčšujú stránku.
Ďalšie kroky
- Referencia Interactivity: možnosti konfigurácie, podrobnosti o podpore editora a objektová forma nastavenia
interactivity. - Prostriedky: ako Blockstudio načítava
script.js,style.cssa ďalšie prostriedky blokov. - WordPress dokumentácia Interactivity API: úplná referencia API vrátane
data-wp-each,data-wp-init,data-wp-runa ďalších direktív, ktoré táto príručka nepokrýva.