Tvorba interaktivních komponent
WordPress bloky jsou ve výchozím nastavení statické. Editor ukládá HTML do databáze, frontend je vykreslí a tím to končí. U mnoha bloků je to přesně tak správně. Některé komponenty ale musí reagovat na interakci uživatele: přepínat obsah, měnit karty, otevírat dialogová okna nebo aktualizovat počítadla.
WordPress Interactivity API přidává blokům reaktivní chování na straně klienta pomocí atributů HTML zvaných direktivy. Píšete data-wp-on--click místo addEventListener a data-wp-bind--hidden místo element.hidden = true. API automaticky zajišťuje reaktivitu, izolaci kontextu a hydrataci.
Blockstudio zajišťuje propojení. Nastavte "interactivity": true ve svém block.json a Blockstudio vygeneruje importmap, načte API v editoru i na frontendu a vyřeší importy modulů ES. Žádné sestavování, žádný bundler ani konfigurace webpacku. Podrobnosti o konfiguraci najdete v referenci Interactivity.
Tento průvodce vás provede čtyřmi kompletními komponentami, z nichž každá představí nové koncepty. Na konci budete mít funkční vzory pro nejběžnější interaktivní prvky UI.
Jak to funguje
Direktivy
Direktivy jsou atributy data-wp-*, které deklarují reaktivní chování přímo ve vašem HTML. Nejčastěji se používají tyto:
| Direktiva | Účel | Příklad |
|---|---|---|
data-wp-interactive |
Definuje jmenný prostor úložiště | data-wp-interactive="myBlock" |
data-wp-context |
Lokální reaktivní stav pro každou instanci | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Obsluha události | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Naváže atribut HTML | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Přepíná třídu CSS | data-wp-class--is-active="context.isActive" |
data-wp-text |
Nastaví textový obsah | data-wp-text="state.count" |
data-wp-style--[prop] |
Nastaví vložený styl | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Globální událost dokumentu | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Spustí zpětné volání při změně stavu | data-wp-watch="callbacks.log" |
data-wp-each |
Prochází pole | data-wp-each="state.items" |
Úložiště
Každý interaktivní blok má úložiště, které vzniká voláním store() se jmenným prostorem a objektem obsahujícím actions, callbacks a případně state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Uvnitř akcí vrací getContext() nejbližší objekt data-wp-context ve stromu DOM směrem nahoru. getElement() vrací odkaz na prvek DOM, který akci vyvolal; hodí se pro čtení atributů data-*.
Kontext a stav
Kontext (data-wp-context) je lokální pro každou instanci bloku. Pokud na stránku vložíte tři akordeony, každý bude mít vlastní hodnotu isOpen. Přepnutí jednoho neovlivní ostatní.
Stav (wp_interactivity_state()) je globální a sdílený mezi všemi instancemi bloku. Použijte jej pro data pocházející ze serveru (například počet komentářů) nebo hodnoty, které mají být všude stejné.
Kontext funguje v editoru i na frontendu. Stav je dostupný pouze na frontendu, protože WordPress jej serializuje do značky script, která není součástí odpovědí REST API editoru.
Akordeon
Nejjednodušší interaktivní vzor: kliknutím na tlačítko přepnete obsah. Tento příklad vyžaduje jen tři direktivy a několik řádků 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;
},
},
});
Jak to funguje:
data-wp-context='{ "isOpen": false }'vytvoří pro tuto instanci lokální logickou hodnotu.- Kliknutím na tlačítko zavoláte
actions.toggle, které přepnecontext.isOpen. data-wp-bind--hidden="!context.isOpen"panel skryje nebo zobrazí.data-wp-bind--aria-expandedadata-wp-textaktualizují stav tlačítka kvůli přístupnosti a vizuálnímu ukazateli.
Každá instance bloku má vlastní kontext, takže na stránku můžete bez dalších úprav vložit více akordeonů. Přepínají se nezávisle.
Karty
Karty představují dva nové koncepty: data-wp-class--* pro přepínání tříd CSS a getElement() pro čtení datových atributů prvku, který akci vyvolal.
Tento příklad používá opakovací pole, aby mohli editoři přidat libovolný počet karet.
{
"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);
}
Co je zde nového:
getElement()vrací{ ref }, kderefje prvek DOM. Zjišťujemedata-index, abychom poznali, na kterou kartu uživatel klikl. Díky tomu nemusíme vytvářet samostatnou akci pro každou kartu.callbacksjsou odvozené hodnoty, které se přepočítají při změně kontextu. Tlačítka karet i panely pomocícallbacks.isActiveTabkontrolují, zda se jejich index shoduje scontext.activeTab.data-wp-class--is-active-tabpřidává nebo odebírá tříduis-active-tabpodle návratové hodnoty zpětného volání.
Modální okno
Modální okno představuje obsluhu událostí na úrovni dokumentu pomocí data-wp-on-document--keydown, které ho zavře po stisknutí Escape, a zavírání kliknutím na pozadí. Ukazuje také správné atributy přístupnosti dialogového okna.
{
"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;
}
},
},
});
Co je zde nového:
data-wp-on-document--keydownnaslouchá nadocumentmísto na samotném prvku. Obsluha se spustí bez ohledu na to, který prvek má fokus, takže Escape funguje odkudkoli.- Zavření kliknutím na pozadí využívá dvě vrstvy: překryvný prvek div zavolá
actions.backdropClick, zatímco vnitřní dialog zavoláactions.stopPropagation, aby kliknutí uvnitř dialogu nezpůsobilo jeho zavření. role="dialog"aaria-modal="true"sdělují čtečkám obrazovky, že jde o modální dialog.aria-labelje navázán tak, aby se uplatnil pouze při zobrazeném modálním okně.- Atribut
hiddenna překryvné vrstvě modální okno skryje a zabrání spuštění posluchače události keydown na dokumentu, když je okno zavřené, protože direktivy na skrytých prvcích jsou pozastaveny.
Tlačítko To se mi líbí se stavem ze serveru
Tento příklad kombinuje stav na straně serveru s akcemi na straně klienta. Počet označení „To se mi líbí“ se inicializuje z PHP pomocí wp_interactivity_state() a tlačítko jej 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;
}
Co je zde nového:
wp_interactivity_state()inicializuje počet z PHP. Hodnota se serializuje do HTML stránky a je dostupná jakostate.countv direktivách a JavaScript.stateacontext: počet je vstate(globální, sdílený), zatímcolikedje vcontext(pro každou instanci zvlášť). Pokud byste měli několik tlačítek „To se mi líbí“ pro stejnou položku, sdílela by počet, ale každé by mohlo samostatně sledovat, zda se vám položka líbí.- Destrukturování z
store(): volánístore()vrací reaktivní objektstate, na který se můžete odkazovat ve svých akcích.
Důležité upozornění: Stav ze serveru je dostupný pouze na frontendu. V editoru se blok vykresluje pomocí REST API, takže wp_interactivity_state() není zahrnut. Náhradní text vykreslený pomocí PHP (<?php echo esc_html( $count ); ?>) se zobrazí jako počáteční hodnota v náhledu editoru. Pro interaktivní stav v editoru použijte místo toho data-wp-context.
Tipy a vzory
Konvence jmenných prostorů. Jako předponu používejte název šablony nebo pluginu: myTheme/accordion, myPlugin/tabs. Zabráníte tak kolizím, když více bloků na stejné stránce používá API Interactivity.
Sestavení není potřeba. Blockstudio načítá script.js jako nativní modul ES a automaticky generuje importmap pro @wordpress/interactivity. Píšete standardní JavaScript s příkazy import a vše funguje okamžitě.
Bloky pouze s direktivami. Pokud váš blok používá jen data-wp-context s data-wp-bind--hidden nebo data-wp-text, soubor script.js vůbec nepotřebujete. API Interactivity se o tyto deklarativní prvky postará. Výše uvedený příklad akordeonu by fungoval i bez JavaScript, kdybyste použili trik s checkboxem, ale řešení pomocí skriptu je čistší.
Ladění pomocí data-wp-watch. Při vývoji přidejte zpětné volání watch, které bude zaznamenávat změny kontextu:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Před nasazením ho odeberte.
Udržujte kontext co nejmenší. Do data-wp-context vkládejte jen hodnoty, které se skutečně mění. Statická data, jako jsou popisky a obsah, ponechte v PHP. Kontext JSON se serializuje do každé instance bloku, takže velké objekty zvětšují stránku.
Další kroky
- Reference Interactivity: možnosti konfigurace, podrobnosti o podpoře editoru a objektová podoba nastavení
interactivity. - Prostředky: jak Blockstudio načítá
script.js,style.cssa další prostředky bloků. - Dokumentace WordPress Interactivity API: úplná referenční příručka API včetně
data-wp-each,data-wp-init,data-wp-runa dalších direktiv, které tento průvodce nepokrývá.