Interaktiivsete komponentide loomine
WordPress plokid on vaikimisi staatilised. Redaktor salvestab HTML andmebaasi, kasutajaliides kuvab selle ja sellega asi piirdub. Paljude plokkide puhul on see täpselt õige. Mõned komponendid peavad aga kasutaja tegevusele reageerima: sisu sisse- ja väljalülitama, vahekaartide vahel liikuma, dialooge avama ja loendureid uuendama.
WordPress Interactivity API lisab plokkidele reaktiivse käitumise kliendis, kasutades HTML atribuute ehk direktiive. Kirjutate data-wp-on--click, mitte addEventListener, ja data-wp-bind--hidden, mitte element.hidden = true. API haldab reaktiivsust, konteksti eraldamist ja hüdratatsiooni automaatselt.
Blockstudio hoolitseb ühendamise eest. Määrake oma block.json-is "interactivity": true ning Blockstudio loob importmapi, laadib API nii redaktoris kui ka kasutajaliideses ja lahendab teie ES-moodulite impordid. Ehitussammu pole, pakendajat pole ega webpacki konfiguratsiooni. Konfiguratsiooni üksikasju vaadake Interactivity viitest.
See juhend käsitleb nelja terviklikku komponenti, millest igaüks tutvustab uusi mõisteid. Lõpuks on teil olemas töötavad mustrid kõige levinumate interaktiivsete UI elementide jaoks.
Kuidas see töötab
Direktiivid
Direktiivid on data-wp-* atribuudid, mis määravad reaktiivse käitumise otse teie HTML-is. Kõige sagedamini kasutatavad:
| Direktiiv | Eesmärk | Näide |
|---|---|---|
data-wp-interactive |
Määrab poe nimeruumi | data-wp-interactive="myBlock" |
data-wp-context |
Iga eksemplari kohalik reaktiivne olek | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Sündmuse töötleja | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Seob atribuudi HTML | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Lülitab klassi CSS sisse või välja | data-wp-class--is-active="context.isActive" |
data-wp-text |
Määrab tekstisisu | data-wp-text="state.count" |
data-wp-style--[prop] |
Määrab tekstisisese stiili | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Dokumendiülene sündmus | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Käivitab tagasihelistuse oleku muutumisel | data-wp-watch="callbacks.log" |
data-wp-each |
Läbib massiivi elemendid | data-wp-each="state.items" |
Pood
Igal interaktiivsel plokil on pood, mis luuakse store() väljakutsega, andes sellele nimeruumi ja objekti, mis sisaldab actions, callbacks ja soovi korral state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Toimingute sees tagastab getContext() DOM-puus lähima ülemise data-wp-context-objekti. getElement() tagastab viite toimingu käivitanud DOM-elemendile; see on kasulik data-* atribuutide lugemiseks.
Kontekst ja olek
Kontekst (data-wp-context) on iga plokieksemplari jaoks kohalik. Kui lisate lehele kolm akordioni, on igal neist oma isOpen väärtus. Ühe lülitamine ei mõjuta teisi.
Olek (wp_interactivity_state()) on üldine ja jagatud ploki kõigi eksemplaride vahel. Kasutage seda serverist pärinevate andmete (nt kommentaaride arvu) või väärtuste jaoks, mis peaksid igal pool samad olema.
Kontekst toimib nii redaktoris kui ka kasutajaliideses. Olek on saadaval ainult kasutajaliideses, sest WordPress serialiseerib selle skriptisildiks, mida redaktori REST API vastused ei sisalda.
Akordion
Lihtsaim interaktiivne muster: klõpsake nuppu ja lülitage sisu sisse või välja. Selles näites on vaja vaid kolme direktiivi ja paari rida JavaScript-i.
{
"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;
},
},
});
Kuidas see töötab:
data-wp-context='{ "isOpen": false }'loob selle eksemplari jaoks kohaliku tõeväärtuse.- Nupul klõpsamine käivitab
actions.toggle, mis muudab väärtusecontext.isOpen. data-wp-bind--hidden="!context.isOpen"peidab või kuvab paneeli.data-wp-bind--aria-expandedjadata-wp-textuuendavad nupu olekut juurdepääsetavuse ja visuaalse tähise jaoks.
Kuna iga plokieksemplar saab oma konteksti, toimib mitme akordioni lisamine lehele kohe. Need lülituvad üksteisest sõltumatult.
Vahekaardid
Vahekaardid tutvustavad kahte uut mõistet: data-wp-class--* klasside CSS lülitamiseks ja getElement() andmeatribuutide lugemiseks toimingu käivitanud elemendilt.
Selles näites kasutatakse kordusvälja, et toimetajad saaksid lisada vajaliku arvu vahekaarte.
{
"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);
}
Mis on uut:
getElement()tagastab{ ref }, kusrefon DOM-element. Loemedata-index, et teada saada, millisel vahekaardil klõpsati. Nii ei pea iga vahekaardi jaoks eraldi toimingut looma.callbackson tuletatud väärtused, mis arvutatakse konteksti muutumisel uuesti. Nii vahekaardinupud kui ka paneelid kasutavadcallbacks.isActiveTab, et kontrollida, kas nende indeks vastab väärtuselecontext.activeTab.data-wp-class--is-active-tablisab või eemaldab klassiis-active-tabvastavalt tagasihelistuse tagastatud väärtusele.
Modaalaken
Modaalaken tutvustab dokumenditaseme sündmuste käsitlemist: data-wp-on-document--keydown abil saab selle Escape-klahviga sulgeda ning taustal klõpsates sulgemise. Näide demonstreerib ka dialoogi korrektseid juurdepääsetavuse atribuute.
{
"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;
}
},
},
});
Mis on uut:
data-wp-on-document--keydownkuulabdocument-il, mitte elemendil endal. Töötleja käivitub fookuses olevast elemendist olenemata, nii et Escape toimib kõikjal.- Taustal klõpsates sulgemine kasutab kahte kihti: ülekate kutsub välja
actions.backdropClick, sisemine dialoog aga kutsub väljaactions.stopPropagation, et dialoogis tehtud klõpsud seda ei sulgeks. role="dialog"jaaria-modal="true"annavad ekraanilugejatele teada, et tegemist on modaalaknaga.aria-labelseotakse nii, et seda rakendatakse ainult siis, kui modaalaken on nähtaval.- Ülekatte atribuut
hiddenpeidab modaalakna ja takistab dokumendi klahvivajutuse kuulaja käivitumist, kui modaalaken on suletud, sest peidetud elementide direktiivide töö peatatakse.
Meeldimisnupp serveri olekuga
See näide ühendab serveripoolse oleku kliendipoolsete toimingutega. Meeldimiste arv lähtestatakse väärtuse PHP alusel, kasutades wp_interactivity_state(), ning nupp uuendab seda klõpsamisel.
{
"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;
}
Mis on uut:
wp_interactivity_state()lähtestab loenduri väärtuse PHP alusel. Väärtus serialiseeritakse lehe HTML-i ja on direktiivides ning JavaScript-is saadaval kujulstate.count.statejacontext: loendur asubstate-is (üldine, jagatud), samas kuilikedasubcontext-is (eksemplaripõhine). Kui samale üksusele oleks mitu meeldimisnuppu, jagaksid need loendurit, kuid igaüks saaks jälgida eraldi meeldimise olekut.store()lahtipakkimine: väljakutsestore()tagastab reaktiivse objektistate, millele saate toimingutes viidata.
Oluline piirang: serveri olek on saadaval ainult kasutajaliideses. Redaktoris renderdatakse plokk REST API abil, seega wp_interactivity_state() puudub. PHP-iga renderdatud asendustekst (<?php echo esc_html( $count ); ?>) kuvatakse redaktori eelvaates algväärtusena. Redaktoris interaktiivse oleku jaoks kasutage selle asemel data-wp-context.
Nõuanded ja mustrid
Nimeruumi kokkulepped. Kasutage eesliitena teema või plugina nime: myTheme/accordion, myPlugin/tabs. Nii väldite kokkupõrkeid, kui mitu sama lehe plokki kasutavad Interactivity API-i.
Ehitussammu pole vaja. Blockstudio laadib script.js natiivse ES-moodulina ja loob @wordpress/interactivity impordimapi automaatselt. Kirjutate standardset JavaScript-i import-lausetega ja see töötab kohe.
Ainult direktiive kasutavad plokid. Kui teie plokk kasutab ainult data-wp-context koos data-wp-bind--hidden või data-wp-text-ga, pole script.js-i üldse vaja. Interactivity API käsitleb neid deklaratiivselt. Ülaltoodud akordioninäide toimiks ka ilma JavaScript-ita, kui kasutaksite märkeruudu nippi, kuid skriptilahendus on puhtam.
Silumine data-wp-watch abil. Lisage arenduse ajaks vaatlusfunktsioon, mis logib konteksti muutusi:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Eemaldage see enne väljalaset.
Hoidke kontekst minimaalne. Lisage data-wp-context-i ainult väärtused, mis tegelikult muutuvad. Staatilised andmed, nagu sildid ja sisu, peaksid jääma PHP-i. Konteksti JSON serialiseeritakse ploki iga eksemplari jaoks, seega suurendavad suured objektid lehe mahtu.
Järgmised sammud
- Interaktiivsuse viide: konfiguratsioonivalikud, redaktori toe üksikasjad ja sätte
interactivityobjektkuju. - Varad: kuidas Blockstudio laadib
script.js,style.cssja muid plokivarasid. - WordPress Interaktiivsuse API dokumentatsioon: täielik API viide, sealhulgas
data-wp-each,data-wp-init,data-wp-runja muud selles juhendis käsitlemata direktiivid.