Pereiti prie turinio

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:

JavaScript
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.

JSON
{
  "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." }
    ]
  }
}
PHP
<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>
JavaScript
import { store, getContext } from '@wordpress/interactivity';

store('myTheme/accordion', {
  actions: {
    toggle: () => {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
});

Kaip tai veikia:

  1. data-wp-context='{ "isOpen": false }' sukuria vietinę loginę reikšmę šiam egzemplioriui.
  2. Spustelėjus mygtuką iškviečiamas actions.toggle, kuris pakeičia context.isOpen reikšmę į priešingą.
  3. data-wp-bind--hidden="!context.isOpen" paslepia arba parodo skydelį.
  4. data-wp-bind--aria-expanded ir data-wp-text atnaujina 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.

JSON
{
  "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." }
        ]
      }
    ]
  }
}
PHP
<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>
JavaScript
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);
    },
  },
});
CSS
.is-active-tab {
  border-bottom-color: currentColor !important;
  color: var(--wp--preset--color--primary, #111);
}

Kas čia naujo:

  • getElement() grąžina { ref }, kur ref yra DOM elementas. Skaitome data-index, kad sužinotume, kuri kortelė buvo spustelėta. Taip nereikia kurti atskiro veiksmo kiekvienai kortelei.
  • callbacks yra išvestinės reikšmės, perskaičiuojamos pasikeitus kontekstui. Tiek kortelių mygtukai, tiek skydeliai naudoja callbacks.isActiveTab, kad patikrintų, ar jų indeksas sutampa su context.activeTab.
  • data-wp-class--is-active-tab pagal grįžtamosios reikšmės rezultatą prideda arba pašalina is-active-tab klasę.

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.

JSON
{
  "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." }
    ]
  }
}
PHP
<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>
JavaScript
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--keydown klausosi document, 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čia actions.stopPropagation, kad dialogo viduje atlikti spustelėjimai jo neuždarytų.
  • role="dialog" ir aria-modal="true" informuoja ekrano skaitytuvus, kad tai modalinis dialogas. aria-label susiejamas taip, kad būtų taikomas tik tada, kai modalinis langas matomas.
  • Perdangos atributas hidden ir 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.

JSON
{
  "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
<?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>
JavaScript
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++;
      }
    },
  },
});
CSS
.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 kaip state.count.
  • state ir context: skaičius saugomas state (visuotinėje, bendroje būsenoje), o liked – 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škvietus store() grąžinamas reaktyvusis state objektas, į 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:

JavaScript
store('myBlock', {
  callbacks: {
    debug: () => {
      const context = getContext();
      console.log('context changed:', { ...context });
    },
  },
});
HTML
<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 interactivity parametro objekto forma.
  • Ištekliai: kaip Blockstudio įkelia script.js, style.css ir kitus blokų išteklius.
  • WordPress Interactivity API dokumentacija: visa API informacija, įskaitant data-wp-each, data-wp-init, data-wp-run ir kitas šiame vadove neaptartas direktyvas.