Interaktyvių komponentų kūrimas
WordPress blokai pagal numatytuosius nustatymus yra statiniai. Redaktorius išsaugo HTML duomenų bazėje, sąsaja jį atvaizduoja, ir tuo viskas baigiasi. Daugeliui blokų tai visiškai tinka. Tačiau kai kurie komponentai turi reaguoti į naudotojo veiksmus: perjungti turinį, korteles, atidaryti dialogus, atnaujinti skaitiklius.
WordPress Interactivity API prideda blokams reaktyvų veikimą kliento pusėje, naudodama HTML atributus, vadinamus direktyvomis. Rašykite data-wp-on--click vietoj addEventListener, data-wp-bind--hidden vietoj element.hidden = true. API automatiškai pasirūpina reaktyvumu, konteksto izoliavimu ir hidratacija.
Blockstudio pasirūpina sujungimu. Nustatykite "interactivity": true savo block.json, o Blockstudio sugeneruos importmap, įkels API tiek redaktoriuje, tiek sąsajoje ir išspręs ES modulių importus. Nereikia kūrimo etapo, rinkinio sudarymo įrankio ar webpack konfigūracijos. Konfigūracijos informaciją rasite Interactivity informacijoje.
Šiame vadove nuosekliai aptariami keturi išsamūs komponentai, kurių kiekvienas pristato naujas sąvokas. Pabaigoje turėsite paruoštus šablonus dažniausiems interaktyviems UI elementams.
Kaip tai veikia
Direktyvos
Direktyvos yra data-wp-* atributai, tiesiogiai jūsų HTML aprašantys reaktyvų veikimą. Dažniausiai naudojamos direktyvos:
| Direktyva | Paskirtis | Pavyzdys |
|---|---|---|
data-wp-interactive |
Apibrėžia saugyklos vardų sritį | data-wp-interactive="myBlock" |
data-wp-context |
Vietinė reaktyvioji kiekvieno egzemplioriaus būsena | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Įvykių apdorojimo funkcija | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Susieja HTML atributą | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Perjungia CSS klasę | data-wp-class--is-active="context.isActive" |
data-wp-text |
Nustato teksto turinį | data-wp-text="state.count" |
data-wp-style--[prop] |
Nustato įterptinį stilių | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Visuotinis dokumento įvykis | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Paleidžia grįžtamojo iškvietimo funkciją pasikeitus būsenai | data-wp-watch="callbacks.log" |
data-wp-each |
Atlieka ciklą per masyvą | data-wp-each="state.items" |
Saugykla
Kiekvienas interaktyvus blokas turi saugyklą, sukuriamą iškvietus store() su vardų sritimi ir objektu, kuriame yra actions, callbacks ir, pasirinktinai, state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Veiksmuose getContext() grąžina artimiausią data-wp-context objektą DOM medyje. getElement() grąžina nuorodą į DOM elementą, kuris suaktyvino veiksmą; ji naudinga skaitant data-* atributus.
Kontekstas ir būsena
Kontekstas (data-wp-context) yra vietinis kiekvienam bloko egzemplioriui. Jei puslapyje įdėsite tris išskleidžiamuosius sąrašus, kiekvienas turės savo isOpen reikšmę. Vieno perjungimas kitų nepaveiks.
Būsena (wp_interactivity_state()) yra visuotinė ir bendra visiems bloko egzemplioriams. Naudokite ją duomenims iš serverio, pavyzdžiui, komentarų skaičiui, arba reikšmėms, kurios visur turi būti vienodos.
Kontekstas veikia ir redaktoriuje, ir sąsajoje. Būsena veikia tik sąsajoje, nes WordPress ją serializuoja į scenarijaus žymą, kuri neįtraukiama į redaktoriaus REST API atsakymus.
Išskleidžiamasis sąrašas
Paprasčiausias interaktyvus šablonas: spustelėkite mygtuką ir perjunkite turinį. Šiam pavyzdžiui reikia tik trijų direktyvų ir kelių eilučių 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;
},
},
});
Kaip tai veikia:
data-wp-context='{ "isOpen": false }'sukuria vietinę loginę reikšmę šiam egzemplioriui.- Spustelėjus mygtuką iškviečiamas
actions.toggle, kuris pakeičiacontext.isOpenreikšmę į priešingą. data-wp-bind--hidden="!context.isOpen"paslepia arba parodo skydelį.data-wp-bind--aria-expandedirdata-wp-textatnaujina mygtuko būseną dėl prieinamumo ir vaizdinio indikatoriaus.
Kadangi kiekvienas bloko egzempliorius turi atskirą kontekstą, puslapyje galima iškart naudoti kelis išskleidžiamuosius sąrašus. Jie perjungiami nepriklausomai.
Kortelės
Kortelės pristato dvi naujas sąvokas: data-wp-class--*, skirtą CSS klasių perjungimui, ir getElement(), skirtą duomenų atributams nuskaityti iš veiksmą suaktyvinusio elemento.
Šiame pavyzdyje naudojamas kartotuvo laukas, kad redaktoriai galėtų pridėti tiek kortelių, kiek reikia.
{
"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);
}
Kas čia naujo:
getElement()grąžina{ ref }, kurrefyra DOM elementas. Skaitomedata-index, kad sužinotume, kuri kortelė buvo spustelėta. Taip nereikia kurti atskiro veiksmo kiekvienai kortelei.callbacksyra išvestinės reikšmės, perskaičiuojamos pasikeitus kontekstui. Tiek kortelių mygtukai, tiek skydeliai naudojacallbacks.isActiveTab, kad patikrintų, ar jų indeksas sutampa sucontext.activeTab.data-wp-class--is-active-tabpagal grįžtamosios reikšmės rezultatą prideda arba pašalinais-active-tabklasę.
Modalinis langas
Modaliniame lange parodomas dokumento lygmens įvykių apdorojimas naudojant data-wp-on-document--keydown, kad langas būtų uždarytas paspaudus Escape, taip pat uždarymas spustelėjus foną. Taip pat pateikiami tinkami dialogo prieinamumo atributai.
{
"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;
}
},
},
});
Kas čia naujo:
data-wp-on-document--keydownklausosidocument, o ne paties elemento įvykių. Apdorojimo funkcija suveikia nepriklausomai nuo to, kuris elementas turi fokusą, todėl Escape veikia iš bet kurios vietos.- Uždarymas spustelėjus foną naudoja du sluoksnius: perdangos div iškviečia
actions.backdropClick, o vidinis dialogas iškviečiaactions.stopPropagation, kad dialogo viduje atlikti spustelėjimai jo neuždarytų. role="dialog"iraria-modal="true"informuoja ekrano skaitytuvus, kad tai modalinis dialogas.aria-labelsusiejamas taip, kad būtų taikomas tik tada, kai modalinis langas matomas.- Perdangos atributas
hiddenir paslepia modalinį langą, ir neleidžia dokumento keydown klausytojui suveikti, kai langas uždarytas, nes paslėptų elementų direktyvos sustabdomos.
Patiktukų mygtukas su serverio būsena
Šiame pavyzdyje serverio būsena derinama su kliento pusės veiksmais. Patiktukų skaičius inicijuojamas iš PHP naudojant wp_interactivity_state(), o mygtuko paspaudimu jis atnaujinamas.
{
"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;
}
Kas čia naujo:
wp_interactivity_state()inicijuoja skaičių iš PHP. Reikšmė serializuojama į puslapio HTML ir direktyvose bei JavaScript pasiekiama kaipstate.count.stateircontext: skaičius saugomasstate(visuotinėje, bendroje būsenoje), oliked–context(kiekvieno egzemplioriaus būsenoje). Jei tam pačiam elementui būtų keli patiktukų mygtukai, jie naudotų bendrą skaičių, bet kiekvienas galėtų atskirai sekti, ar naudotojui elementas patinka.- Išskaidymas iš
store(): iškvietusstore()grąžinamas reaktyvusisstateobjektas, į kurį galite kreiptis veiksmuose.
Svarbi išlyga: serverio būsena veikia tik sąsajoje. Redaktoriuje blokas atvaizduojamas per REST API, todėl wp_interactivity_state() neįtraukiamas. PHP pateiktas atsarginis tekstas (<?php echo esc_html( $count ); ?>) redaktoriaus peržiūroje rodomas kaip pradinė reikšmė. Interaktyviai būsenai redaktoriuje naudokite data-wp-context.
Patarimai ir šablonai
Vardų sričių susitarimai. Kaip priešdėlį naudokite temos arba įskiepio pavadinimą: myTheme/accordion, myPlugin/tabs. Taip išvengsite konfliktų, kai keliame puslapyje esantys blokai naudoja Interactivity API.
Kūrimo etapo nereikia. Blockstudio įkelia script.js kaip savąjį ES modulį ir automatiškai sugeneruoja @wordpress/interactivity importmap. Rašykite įprastą JavaScript su import sakiniais, ir viskas veiks iškart.
Blokai tik su direktyvomis. Jei jūsų bloke naudojamos tik data-wp-context su data-wp-bind--hidden arba data-wp-text, jums visai nereikia script.js. Interactivity API tai apdoroja deklaratyviai. Aukščiau pateiktas išskleidžiamojo sąrašo pavyzdys galėtų veikti ir be JavaScript, jei naudotumėte varnelės triuką, tačiau scenarijumi pagrįstas būdas yra švaresnis.
Derinimas naudojant data-wp-watch. Pridėkite stebėjimo grįžtamojo iškvietimo funkciją, kad kūrimo metu registruotumėte konteksto pokyčius:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Pašalinkite ją prieš išleisdami.
Kontekstą laikykite kuo mažesnį. Į data-wp-context įtraukite tik tas reikšmes, kurios iš tikrųjų kinta. Nekintantys duomenys, pavyzdžiui, etiketės ir turinys, turėtų likti PHP. Konteksto JSON serializuojamas kiekviename bloko egzemplioriuje, todėl dideli objektai padidina puslapio dydį.
Tolesni žingsniai
- Interactivity informacija: konfigūravimo parinktys, informacija apie redaktoriaus palaikymą ir
interactivityparametro objekto forma. - Ištekliai: kaip Blockstudio įkelia
script.js,style.cssir kitus blokų išteklius. - WordPress Interactivity API dokumentacija: visa API informacija, įskaitant
data-wp-each,data-wp-init,data-wp-runir kitas šiame vadove neaptartas direktyvas.