Interaktīvu komponentu veidošana
WordPress bloki pēc noklusējuma ir statiski. Redaktors saglabā HTML datubāzē, priekšgals to attēlo, un ar to viss beidzas. Daudziem blokiem tas ir tieši pareizi. Taču dažiem komponentiem jāreaģē uz lietotāja mijiedarbību: jāpārslēdz saturs, cilnes, jāatver dialogi un jāatjaunina skaitītāji.
WordPress Interactivity API pievieno blokiem reaktīvu darbību klienta pusē, izmantojot HTML atribūtus, ko sauc par direktīvām. Rakstiet data-wp-on--click, nevis addEventListener; data-wp-bind--hidden, nevis element.hidden = true. API automātiski nodrošina reaktivitāti, konteksta izolāciju un hidratāciju.
Blockstudio nodrošina nepieciešamo sasaisti. Iestatiet "interactivity": true savā block.json, un Blockstudio ģenerē importmap, ielādē API gan redaktorā, gan priekšgalā un atrisina jūsu ES moduļu importus. Nav nepieciešama būvēšanas darbība, komplektētājs vai webpack konfigurācija. Konfigurācijas informāciju skatiet Interactivity uzziņu materiālā.
Šajā rokasgrāmatā soli pa solim aplūkoti četri pilnīgi komponenti, katrs iepazīstina ar jauniem jēdzieniem. Beigās jums būs gatavi paraugi visbiežāk izmantotajiem interaktīvajiem UI elementiem.
Kā tas darbojas
Direktīvas
Direktīvas ir data-wp-* atribūti, kas tieši jūsu HTML deklarē reaktīvu darbību. Visbiežāk izmantotās:
| Direktīva | Nolūks | Piemērs |
|---|---|---|
data-wp-interactive |
Definē krātuves nosaukumtelpu | data-wp-interactive="myBlock" |
data-wp-context |
Lokāls reaktīvs stāvoklis katrai instancei | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Notikumu apstrādātājs | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Piesaista HTML atribūtu | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Pārslēdz CSS klasi | data-wp-class--is-active="context.isActive" |
data-wp-text |
Iestata teksta saturu | data-wp-text="state.count" |
data-wp-style--[prop] |
Iestata iekļauto stilu | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Globāls dokumenta notikums | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Palaiž atzvanes funkciju, kad mainās stāvoklis | data-wp-watch="callbacks.log" |
data-wp-each |
Iterē masīva elementus | data-wp-each="state.items" |
Krātuve
Katram interaktīvajam blokam ir krātuve, ko izveido, izsaucot store() ar nosaukumtelpu un objektu, kurā ir actions, callbacks un, pēc izvēles, state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Darbībās getContext() atgriež tuvāko data-wp-context objektu DOM kokā. getElement() atgriež atsauci uz DOM elementu, kas izraisīja darbību; tā noder, lai nolasītu data-* atribūtus.
Konteksts un stāvoklis
Konteksts (data-wp-context) ir lokāls katrai bloka instancei. Ja lapā ievietojat trīs akordeonus, katram ir sava isOpen vērtība. Pārslēdzot vienu, pārējie nemainās.
Stāvoklis (wp_interactivity_state()) ir globāls un kopīgs visām bloka instancēm. Izmantojiet to datiem, kas nāk no servera (piemēram, komentāru skaitam), vai vērtībām, kam visur jābūt vienādām.
Konteksts darbojas gan redaktorā, gan priekšgalā. Stāvoklis darbojas tikai priekšgalā, jo WordPress serializē to skripta tagā, kas nav iekļauts redaktora REST API atbildēs.
Akordeons
Vienkāršākais interaktīvais paraugs: noklikšķiniet uz pogas, lai pārslēgtu saturu. Šajā piemērā vajadzīgas tikai trīs direktīvas un dažas JavaScript rindas.
{
"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;
},
},
});
Darbības princips:
data-wp-context='{ "isOpen": false }'izveido lokālu Būla vērtību šai instancei.- Noklikšķinot uz pogas, tiek izsaukts
actions.toggle, kas apgriežcontext.isOpenvērtību. data-wp-bind--hidden="!context.isOpen"paslēpj vai parāda paneli.data-wp-bind--aria-expandedundata-wp-textatjaunina pogas stāvokli piekļūstamībai un vizuālajam indikatoram.
Tā kā katrai bloka instancei ir savs konteksts, vairākus akordeonus lapā var izvietot uzreiz. Tie darbojas neatkarīgi cits no cita.
Cilnes
Cilnes ievieš divus jaunus jēdzienus: data-wp-class--* klašu CSS pārslēgšanai un getElement() datu atribūtu nolasīšanai no elementa, kas izraisīja darbību.
Šajā piemērā izmantots atkārtotāja lauks, lai redaktori varētu pievienot vajadzīgo ciļņu skaitu.
{
"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 šeit ir jauns:
getElement()atgriež{ ref }, kurrefir DOM elements. Nolasāmdata-index, lai noteiktu, kura cilne tika noklikšķināta. Tādējādi katrai cilnei nav jāveido atsevišķa darbība.callbacksir atvasinātas vērtības, kas tiek aprēķinātas no jauna, mainoties kontekstam. Gan ciļņu pogas, gan paneļi izmantocallbacks.isActiveTab, lai pārbaudītu, vai to indekss atbilstcontext.activeTab.data-wp-class--is-active-tabpievieno vai noņem klasiis-active-tabatkarībā no atzvanes funkcijas atgrieztās vērtības.
Modālais logs
Modālais logs iepazīstina ar dokumenta līmeņa notikumu apstrādi: data-wp-on-document--keydown aizver logu, nospiežot Escape, un klikšķis uz fona to aizver. Piemērā parādīti arī pareizi dialoga piekļūstamības atribūti.
{
"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 šeit ir jauns:
data-wp-on-document--keydownklausās notikumus uzdocument, nevis pašā elementā. Apstrādātājs tiek izpildīts neatkarīgi no tā, kuram elementam ir fokuss, tāpēc Escape darbojas jebkurā vietā.- Aizvēršana, noklikšķinot uz fona, izmanto divus slāņus: pārklājuma div izsauc
actions.backdropClick, bet iekšējais dialoga logs izsaucactions.stopPropagation, lai novērstu tā aizvēršanu, noklikšķinot dialoga iekšpusē. role="dialog"unaria-modal="true"informē ekrāna lasītājus, ka tas ir modāls dialogs.aria-labelir piesaistīts tā, lai darbotos tikai tad, kad modālais logs ir redzams.hiddenatribūts pārklājumā gan paslēpj modālo logu, gan neļauj dokumenta taustiņa nospiešanas klausītājam darboties, kamēr logs ir aizvērts, jo direktīvas paslēptos elementos tiek apturētas.
Poga “Patīk” ar servera stāvokli
Šajā piemērā apvienots servera puses stāvoklis ar klienta puses darbībām. Patīk skaits tiek inicializēts no PHP, izmantojot wp_interactivity_state(), un, noklikšķinot uz pogas, tas tiek atjaunināts.
{
"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 šeit ir jauns:
wp_interactivity_state()inicializē skaitu no PHP. Vērtība tiek serializēta lapas HTML un ir pieejama kāstate.countdirektīvās un JavaScript.stateuncontext: skaits atrodasstate(globālā, koplietojamā stāvoklī), betlikedatrodascontext(katrai instancei atsevišķā kontekstā). Ja vienam elementam būtu vairākas pogas “Patīk”, tās koplietotu skaitu, bet katra varētu atsevišķi uzskaitīt, vai tai ir atzīmēts “Patīk”.- Destrukturēšana no
store(): izsaukumsstore()atgriež reaktīvustateobjektu, uz kuru varat atsaukties savās darbībās.
Svarīga piebilde: servera stāvoklis darbojas tikai priekšgalā. Redaktorā bloks tiek attēlots ar REST API, tāpēc wp_interactivity_state() nav iekļauts. Teksts PHP attēlotajā rezerves variantā (<?php echo esc_html( $count ); ?>) redaktora priekšskatījumā tiek rādīts kā sākotnējā vērtība. Redaktorā interaktīvam stāvoklim izmantojiet data-wp-context.
Padomi un paraugi
Nosaukumtelpu veidošanas ieteikumi. Izmantojiet savas tēmas vai spraudņa nosaukumu kā prefiksu: myTheme/accordion, myPlugin/tabs. Tas novērš sadursmes, ja vairākos vienas lapas blokos tiek izmantots Interactivity API.
Nav nepieciešama būvēšanas darbība. Blockstudio ielādē script.js kā iebūvētu ES moduli un automātiski ģenerē @wordpress/interactivity paredzēto importmap. Rakstiet standarta JavaScript ar import priekšrakstiem, un tas uzreiz darbosies.
Bloki, kuros izmanto tikai direktīvas. Ja jūsu blokā izmanto tikai data-wp-context kopā ar data-wp-bind--hidden vai data-wp-text, script.js nav vajadzīgs. Interactivity API to nodrošina deklaratīvi. Iepriekš redzamais akordeona piemērs darbotos arī bez JavaScript, izmantojot izvēles rūtiņas paņēmienu, taču pieeja ar skriptu ir vienkāršāka.
Atkļūdošana ar data-wp-watch. Izstrādes laikā pievienojiet novērošanas atzvanes funkciju, lai reģistrētu konteksta izmaiņas:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Pirms publicēšanas noņemiet to.
Saglabājiet kontekstu minimālu. Ievietojiet data-wp-context tikai tās vērtības, kas tiešām mainās. Statiskiem datiem, piemēram, etiķetēm un saturam, jāpaliek PHP. Konteksts JSON tiek serializēts katrā bloka instancē, tāpēc lieli objekti palielina lapas izmēru.
Nākamie soļi
- Interactivity uzziņu materiāls: konfigurācijas opcijas, informācija par redaktora atbalstu un iestatījuma
interactivityobjekta forma. - Resursi: kā Blockstudio ielādē
script.js,style.cssun citus bloku resursus. - WordPress Interactivity API dokumentācija: pilna API uzziņu informācija, tostarp par
data-wp-each,data-wp-init,data-wp-runun citām direktīvām, kas nav aplūkotas šajā rokasgrāmatā.