Vuorovaikutteisten komponenttien rakentaminen
WordPress-lohkot ovat oletuksena staattisia. Muokkain tallentaa HTML tietokantaan, käyttöliittymä renderöi sen, ja siihen tarina päättyy. Monille lohkoille tämä on juuri oikein. Jotkin komponentit kuitenkin tarvitsevat käyttäjän vuorovaikutukseen reagoimista: sisällön avaamista ja sulkemista, välilehtien vaihtamista, valintaikkunoiden avaamista ja laskurien päivittämistä.
WordPress Interactivity API lisää lohkoihin reaktiivisen, asiakaspuolen toiminnan käyttämällä HTML-attribuutteja, joita kutsutaan direktiiveiksi. Kirjoitat data-wp-on--click etkä addEventListener, data-wp-bind--hidden etkä element.hidden = true. API huolehtii automaattisesti reaktiivisuudesta, kontekstin eristämisestä ja nesteytyksestä.
Blockstudio hoitaa kytkennät. Aseta "interactivity": true tiedostossasi block.json, niin Blockstudio luo importmapin, lataa API sekä muokkaimessa että käyttöliittymässä ja ratkaisee ES-moduulien tuonnit. Ei rakennusvaihetta, paketoijaa tai webpack-asetuksia. Katso Interactivity-viite saadaksesi lisätietoja määrityksistä.
Tämä opas käy läpi neljä täydellistä komponenttia, joista jokainen esittelee uusia käsitteitä. Lopuksi sinulla on toimivat mallit yleisimpiin vuorovaikutteisiin UI-elementteihin.
Näin se toimii
Direktiivit
Direktiivit ovat data-wp-*-attribuutteja, jotka määrittävät reaktiivisen toiminnan suoraan HTML-elementeissäsi. Yleisimmin käytetyt:
| Direktiivi | Tarkoitus | Esimerkki |
|---|---|---|
data-wp-interactive |
Määritä kaupan nimiavaruus | data-wp-interactive="myBlock" |
data-wp-context |
Paikallinen reaktiivinen tila kutakin esiintymää kohden | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Tapahtumankäsittelijä | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Sido HTML-attribuutti | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Ota CSS-luokka käyttöön tai poista se käytöstä | data-wp-class--is-active="context.isActive" |
data-wp-text |
Aseta tekstisisältö | data-wp-text="state.count" |
data-wp-style--[prop] |
Aseta sisäinen tyyli | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Dokumentin yleinen tapahtuma | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Suorita takaisinkutsu, kun tila muuttuu | data-wp-watch="callbacks.log" |
data-wp-each |
Käy taulukon arvot läpi | data-wp-each="state.items" |
Kauppa
Jokaisella vuorovaikutteisella lohkolla on kauppa, joka luodaan kutsumalla store() nimiavaruudella ja objektilla, joka sisältää actions, callbacks ja halutessasi state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Toimintojen sisällä getContext() palauttaa lähimmän data-wp-context-objektin DOM-puussa ylöspäin. getElement() palauttaa viitteen toiminnon käynnistäneeseen DOM-elementtiin, mikä on hyödyllistä data-*-attribuuttien lukemiseen.
Konteksti ja tila
Konteksti (data-wp-context) on paikallinen kullekin lohkon esiintymälle. Jos sivulla on kolme haitarivalikkoa, jokaisella on oma isOpen-arvonsa. Yhden vaihtaminen ei vaikuta muihin.
Tila (wp_interactivity_state()) on yleinen ja jaettu lohkon kaikkien esiintymien kesken. Käytä sitä palvelimelta tuleville tiedoille (kuten kommenttimäärälle) tai arvoille, joiden pitäisi olla kaikkialla samoja.
Konteksti toimii sekä muokkaimessa että käyttöliittymässä. Tila on käytettävissä vain käyttöliittymässä, koska WordPress sarjoittaa sen skriptitunnisteeseen, jota ei sisällytetä muokkaimen REST API-vastauksiin.
Haitarivalikko
Yksinkertaisin vuorovaikutteinen malli: napsauta painiketta ja avaa tai sulje sisältöä. Tässä esimerkissä tarvitaan vain kolme direktiiviä ja muutama rivi JavaScript-koodia.
{
"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;
},
},
});
Näin se toimii:
data-wp-context='{ "isOpen": false }'luo tälle esiintymälle paikallisen totuusarvon.- Painikkeen napsauttaminen kutsuu
actions.toggle-toimintoa, joka vaihtaa arvoncontext.isOpen. data-wp-bind--hidden="!context.isOpen"piilottaa tai näyttää paneelin.data-wp-bind--aria-expandedjadata-wp-textpäivittävät painikkeen tilan saavutettavuutta ja visuaalista ilmaisinta varten.
Koska jokainen lohkon esiintymä saa oman kontekstinsa, useiden haitarivalikkojen lisääminen sivulle toimii suoraan. Ne avautuvat ja sulkeutuvat toisistaan riippumatta.
Välilehdet
Välilehdet esittelevät kaksi uutta käsitettä: data-wp-class--*-direktiivin CSS-luokkien vaihtamiseen ja getElement()-direktiivin tapahtuman käynnistäneen elementin data-attribuuttien lukemiseen.
Tässä esimerkissä käytetään toistinkenttää, jotta muokkaajat voivat lisätä tarvitsemansa määrän välilehtiä.
{
"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);
}
Uutta tässä:
getElement()palauttaa{ ref }-arvon, jossarefon DOM-elementti. Luemmedata-index-arvon saadaksemme selville, mitä välilehteä napsautettiin. Näin jokaiselle välilehdelle ei tarvitse luoda erillistä toimintoa.callbacksovat johdettuja arvoja, jotka lasketaan uudelleen kontekstin muuttuessa. Sekä välilehtipainikkeet että paneelit tarkistavatcallbacks.isActiveTab-arvon avulla, vastaako niiden indeksi arvoacontext.activeTab.data-wp-class--is-active-tablisääis-active-tab-luokan tai poistaa sen takaisinkutsun palautusarvon perusteella.
Modaali
Modaali esittelee dokumenttitason tapahtumien käsittelyn data-wp-on-document--keydown-direktiivillä, jolla se suljetaan Escape-näppäimellä, sekä napsauttamalla taustaa. Lisäksi esimerkissä näytetään dialogin asianmukaiset saavutettavuusattribuutit.
{
"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;
}
},
},
});
Uutta tässä:
data-wp-on-document--keydownkuunteleedocument-elementtiä itse elementin sijaan. Käsittelijä suoritetaan riippumatta siitä, mikä elementti on kohdistettuna, joten Escape toimii kaikkialla.- Taustaa napsauttamalla sulkeminen käyttää kahta tasoa: peittävän div-elementin kutsu
actions.backdropClick, kun taas sisäinen dialogi kutsuuactions.stopPropagationestääkseen dialogin sisällä olevia napsautuksia sulkemasta sitä. role="dialog"jaaria-modal="true"ilmoittavat näytönlukijoille, että kyseessä on modaalinen dialogi.aria-labelsidotaan niin, että se on käytössä vain modaalin ollessa näkyvissä.- Peittävän elementin
hidden-attribuutti sekä piilottaa modaalin että estää dokumenttitason keydown-kuuntelijaa suorittumasta modaalin ollessa suljettuna, sillä piilotettujen elementtien direktiivit on keskeytetty.
Tykkäyspainike palvelintilalla
Tässä esimerkissä yhdistetään palvelinpuolen tila asiakaspuolen toimintoihin. Tykkäysmäärä alustetaan arvosta PHP käyttäen wp_interactivity_state()-toimintoa, ja painike päivittää sen napsautettaessa.
{
"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;
}
Uutta tässä:
wp_interactivity_state()alustaa määrän arvosta PHP. Arvo sarjoitetaan sivun HTML-tunnisteeseen, ja se on käytettävissä direktiiveissä jastate.count-elementeissä muodossa JavaScript.statejacontext: määrä on arvossastate(yleinen, jaettu), kun taaslikedon arvossacontext(esiintymäkohtainen). Jos samalla kohteella olisi useita tykkäyspainikkeita, ne jakaisivat määrän, mutta jokainen voisi seurata omaa tykkäystilaansa.- Purkaminen osiin kohteesta
store(): kutsustore()palauttaa reaktiivisenstate-objektin, johon voit viitata toiminnoissasi.
Tärkeä huomio: Palvelintila on käytettävissä vain käyttöliittymässä. Muokkaimessa lohko renderöidään REST API -mallin kautta, joten wp_interactivity_state() ei sisälly siihen. PHP-renderöity varateksti (<?php echo esc_html( $count ); ?>) näkyy muokkaimen esikatselussa alkuarvona. Käytä sen sijaan arvoa data-wp-context, jos haluat tilan toimivan vuorovaikutteisesti muokkaimessa.
Vinkkejä ja malleja
Nimiavaruuksien käytännöt. Käytä teeman tai lisäosan nimeä etuliitteenä: myTheme/accordion, myPlugin/tabs. Näin vältät törmäykset, kun useat saman sivun lohkot käyttävät Interactivity API-toimintoa.
Rakennusvaihetta ei tarvita. Blockstudio lataa script.js-moduulin natiivina ES-moduulina ja luo @wordpress/interactivity-importmapin automaattisesti. Kirjoitat tavallista JavaScript-koodia import-lausekkeilla, ja se toimii heti.
Vain direktiivejä käyttävät lohkot. Jos lohkossasi käytetään vain data-wp-context-direktiiviä yhdessä data-wp-bind--hidden– tai data-wp-text-direktiivin kanssa, et tarvitse lainkaan script.js-skriptiä. Interactivity API hoitaa nämä deklaratiivisesti. Yllä oleva haitarivalikkoesimerkki toimisi ilman JavaScript-skriptiä, jos käyttäisit valintaruutukikkaa, mutta skriptilähestymistapa on siistimpi.
Virheenkorjaus data-wp-watch-toiminnolla. Lisää watch-takaisinkutsu, jolla voit kirjata kontekstin muutokset kehityksen aikana:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Poista se ennen julkaisua.
Pidä konteksti suppeana. Lisää arvoon data-wp-context vain tosiasiassa muuttuvia arvoja. Staattisten tietojen, kuten otsikoiden ja sisällön, pitäisi pysyä arvossa PHP. Kontekstin JSON sarjoitetaan lohkon jokaiseen esiintymään, joten suuret objektit kasvattavat sivun kokoa.
Seuraavat vaiheet
- Interactivity-viite: määritysasetukset, editorin tukitiedot ja
interactivity-asetuksen objektimuoto. - Resurssit: miten Blockstudio lataa
script.js-,style.css– ja muut lohkoresurssit. - WordPress Interactivity API -dokumentaatio: kattava API-viite, joka sisältää
data-wp-each-,data-wp-init-,data-wp-run– ja muita tässä oppaassa käsittelemättömiä direktiivejä.