Interaktív komponensek építése
A WordPress blokkok alapértelmezés szerint statikusak. A szerkesztő elmenti a HTML értéket az adatbázisba, a frontend megjeleníti, és ezzel véget is ér a történet. Sok blokk esetében ez pontosan így helyes. Egyes komponenseknek azonban reagálniuk kell a felhasználói interakciókra: tartalmak ki- és bekapcsolására, lapok közötti váltásra, párbeszédablakok megnyitására, számlálók frissítésére.
A WordPress Interaktivitás API reaktív, kliensoldali viselkedést ad a blokkokhoz a direktíváknak nevezett HTML attribútumok segítségével. data-wp-on--click-t írsz addEventListener helyett, data-wp-bind--hidden-t pedig element.hidden = true helyett. A API automatikusan kezeli a reaktivitást, a kontextus elkülönítését és a hidratálást.
A Blockstudio gondoskodik az összekötésről. Állítsd be a "interactivity": true értékét a block.json fájlban, és a Blockstudio létrehozza az importtérképet, betölti a API modult a szerkesztőben és a frontendben is, valamint feloldja az ES-modulok importjait. Nincs szükség fordítási lépésre, csomagolóra vagy webpack-konfigurációra. A konfiguráció részleteiért lásd az Interaktivitási referenciát.
Ez az útmutató négy teljes komponensen vezet végig, és mindegyik új fogalmakat mutat be. A végére kész megoldásmintáid lesznek a leggyakoribb interaktív UI elemekhez.
Működés
Direktívák
A direktívák data-wp-* attribútumok, amelyek közvetlenül a HTML-ben határozzák meg a reaktív viselkedést. A leggyakrabban használtak:
| Direktíva | Cél | Példa |
|---|---|---|
data-wp-interactive |
A tároló névterének meghatározása | data-wp-interactive="myBlock" |
data-wp-context |
Példányonkénti helyi reaktív állapot | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Eseménykezelő | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Egy HTML attribútum kötése | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Egy CSS osztály be- és kikapcsolása | data-wp-class--is-active="context.isActive" |
data-wp-text |
Szöveges tartalom beállítása | data-wp-text="state.count" |
data-wp-style--[prop] |
Inline stílus beállítása | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Globális dokumentumesemény | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Visszahívás futtatása állapotváltozáskor | data-wp-watch="callbacks.log" |
data-wp-each |
Tömb elemeinek bejárása | data-wp-each="state.items" |
A tároló
Minden interaktív blokknak van tárolója. Ezt a store() hívásával hozhatod létre: meg kell adnod egy névteret, valamint egy objektumot, amely actions-t, callbacks-t és opcionálisan state-t tartalmaz:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
A műveleteken belül a getContext() a DOM-fában legközelebb eső data-wp-context objektumot adja vissza. A getElement() hivatkozást ad vissza a műveletet kiváltó DOM-elemre; ez hasznos a data-* attribútumok kiolvasásához.
Kontextus és állapot
A kontextus (data-wp-context) minden blokkpéldányban helyi. Ha három harmonikát helyezel el egy oldalon, mindegyiknek saját isOpen értéke lesz. Az egyik átkapcsolása nincs hatással a többire.
Az állapot (wp_interactivity_state()) globális, és egy blokk minden példánya megosztja. Olyan adatokhoz használd, amelyek a szerverről érkeznek, például a hozzászólások számához, vagy olyan értékekhez, amelyeknek mindenhol azonosnak kell lenniük.
A kontextus a szerkesztőben és a frontendben egyaránt működik. Az állapot csak a frontendben érhető el, mert a WordPress egy olyan scriptcímkébe szerializálja, amely nem szerepel a szerkesztői REST API válaszaiban.
Harmonika
A legegyszerűbb interaktív megoldásminta: kattints egy gombra, és kapcsold át a tartalom láthatóságát. Ehhez a példához mindössze három direktíva és néhány sor JavaScript szükséges.
{
"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;
},
},
});
Működése:
- A
data-wp-context='{ "isOpen": false }'helyi logikai értéket hoz létre ehhez a példányhoz. - A gombra kattintva meghívódik a
actions.toggle, amely megfordítja acontext.isOpenértékét. - A
data-wp-bind--hidden="!context.isOpen"elrejti vagy megjeleníti a panelt. - A
data-wp-bind--aria-expandedés adata-wp-textfrissíti a gomb állapotát a kisegítő lehetőségek és a vizuális jelzés érdekében.
Mivel minden blokkpéldány saját kontextust kap, több harmonika elhelyezése az oldalon azonnal működik. Egymástól függetlenül kapcsolhatók át.
Lapfülek
A lapfülek két új fogalmat vezetnek be: a data-wp-class--* direktívát a CSS osztályok kapcsolgatásához, valamint a getElement() direktívát az eseményt kiváltó elem adatattribútumainak kiolvasásához.
Ez a példa ismétlőmezőt használ, hogy a szerkesztők tetszőleges számú lapfület adhassanak hozzá.
{
"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);
}
Újdonságok:
getElement()arefDOM-elemmel együtt visszaadja a{ ref }értéket. Adata-indexkiolvasásával megtudhatjuk, melyik lapfülre kattintottak. Így nem kell minden lapfülhöz külön műveletet létrehozni.- A
callbacksszármaztatott értékek, amelyek a kontextus változásakor újra kiértékelődnek. A lapfülgombok és a panelek is acallbacks.isActiveTabsegítségével ellenőrzik, hogy az indexük megegyezik-e acontext.activeTabértékével. - A
data-wp-class--is-active-taba visszahívás visszatérési értéke alapján hozzáadja vagy eltávolítja ais-active-tabosztályt.
Modális ablak
A modális ablak bemutatja a dokumentumszintű eseménykezelést: a data-wp-on-document--keydown az Escape billentyű lenyomására bezárja az ablakot, és a háttérre kattintva is bezárható. A példa a párbeszédablakok akadálymentességi attribútumainak helyes használatát is bemutatja.
{
"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;
}
},
},
});
Újdonságok:
- A
data-wp-on-document--keydownadocument-en figyeli az eseményt az elem helyett. A kezelő a fókuszban lévő elemtől függetlenül lefut, így az Escape bárhonnan működik. - A háttérre kattintva bezárás két réteget használ: a fedőréteg divje meghívja a
actions.backdropClick-t, míg a belső párbeszédablak aactions.stopPropagation-t, így a belső kattintások nem zárják be az ablakot. - A
role="dialog"és aaria-modal="true"jelzi a képernyőolvasóknak, hogy ez modális párbeszédablak. Aaria-labelkötése biztosítja, hogy csak akkor legyen érvényes, amikor a modális ablak látható. - A fedőrétegen lévő
hiddenattribútum elrejti a modális ablakot, és megakadályozza, hogy a dokumentum keydown-eseményfigyelője lefusson, amikor az ablak zárva van, mert a rejtett elemeken lévő direktívák szünetelnek.
Tetszésgomb szerveroldali állapottal
Ez a példa szerveroldali állapotot és kliensoldali műveleteket kombinál. A tetszések száma a PHP értékéből, a wp_interactivity_state() segítségével inicializálódik, a gomb pedig kattintáskor frissíti.
{
"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;
}
Újdonságok:
- A
wp_interactivity_state()a PHP értékéből inicializálja a számlálót. Az érték a lap HTML részébe szerializálódik, ésstate.countformájában érhető el a direktívákban és a JavaScript-ben. stateéscontext: a számláló astate-ban található (globális, megosztott), míg alikedacontext-ben (példányonként). Ha ugyanahhoz az elemhez több tetszésgomb tartozna, megosztanák a számlálót, de mindegyik külön követhetné a saját tetszésállapotát.- Kibontás a
store()-ből: astore()hívása egy reaktívstateobjektumot ad vissza, amelyre hivatkozhatsz a műveleteidben.
Fontos tudnivaló: A szerveroldali állapot csak a frontendben érhető el. A szerkesztőben a blokk a REST API segítségével jelenik meg, így a wp_interactivity_state() nincs benne. A PHP által megjelenített tartalék szöveg (<?php echo esc_html( $count ); ?>) jelenik meg kezdeti értékként a szerkesztő előnézetében. A szerkesztőben is interaktív állapothoz használd inkább a data-wp-context-t.
Tippek és minták
Névtér-konvenciók. Előtagként használd a témád vagy bővítményed nevét: myTheme/accordion, myPlugin/tabs. Ezzel elkerülhetők az ütközések, ha ugyanazon az oldalon több blokk használja az Interaktivitás API-t.
Nincs szükség fordítási lépésre. A Blockstudio natív ES-modulként tölti be a script.js-t, és automatikusan létrehozza a @wordpress/interactivity importtérképét. Szabványos JavaScript-t írsz import utasításokkal, és azonnal működik.
Csak direktívákat használó blokkok. Ha a blokkod csak data-wp-bind--hidden-et vagy data-wp-text-t használó data-wp-context-kat tartalmaz, egyáltalán nincs szükséged script.js-ra. Az Interaktivitás API deklaratív módon kezeli ezeket. A fenti harmonikapélda JavaScript nélkül is működhetne, ha jelölőnégyzetes trükköt használnál, de a szkriptalapú megoldás tisztább.
Hibakeresés data-wp-watch segítségével. Fejlesztés közben naplózd a kontextus változásait egy figyelő-visszahívás hozzáadásával:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Élesítés előtt távolítsd el.
Tartsd minimálisan a kontextust. Csak azokat az értékeket tedd a data-wp-context-be, amelyek valóban változnak. Az olyan statikus adatokat, mint a címkék és a tartalom, hagyd a PHP-ben. A kontextus JSON minden blokkpéldányba szerializálódik, ezért a nagy objektumok növelik az oldal méretét.
Következő lépések
- Interaktivitási referencia: konfigurációs beállítások, a szerkesztő támogatásának részletei és a
interactivitybeállítás objektumalakja. - Eszközök: hogyan tölti be a Blockstudio a
script.js, astyle.cssés más blokk-eszközöket. - WordPress Interaktivitás API dokumentáció: a teljes API referencia, beleértve a
data-wp-each, adata-wp-init, adata-wp-runés az ebben az útmutatóban nem tárgyalt további direktívákat.