Preskoči na vsebino

Izdelava interaktivnih komponent

WordPress bloki so privzeto statični. Urejevalnik shrani HTML v zbirko podatkov, frontend pa jo izriše in s tem je zgodba končana. Pri številnih blokih je to povsem ustrezno. Nekatere komponente pa se morajo odzivati na uporabniške interakcije: preklapljanje vsebine, menjavanje zavihkov, odpiranje pogovornih oken in posodabljanje števcev.

WordPress Interactivity API doda blokom reaktivno delovanje na strani odjemalca z atributi HTML, imenovanimi direktive. Namesto addEventListener napišete data-wp-on--click, namesto element.hidden = true pa data-wp-bind--hidden. API samodejno poskrbi za reaktivnost, izolacijo konteksta in hidracijo.

Blockstudio poskrbi za povezovanje. Nastavite "interactivity": true v svojem block.json, Blockstudio pa ustvari importmap, naloži API v urejevalniku in na frontendu ter razreši vaše uvoze modulov ES. Brez koraka gradnje, povezovalnika ali konfiguracije webpacka. Podrobnosti o konfiguraciji najdete v referenci Interactivity.

Ta vodnik vas vodi skozi štiri celovite komponente, od katerih vsaka predstavi nove koncepte. Ob koncu boste poznali delujoče vzorce za najpogostejše interaktivne elemente UI.

Kako deluje

Direktive

Direktive so atributi data-wp-*, ki določajo reaktivno vedenje neposredno v vašem HTML. Najpogosteje uporabljene so:

Direktiva Namen Primer
data-wp-interactive Določi imenski prostor shrambe data-wp-interactive="myBlock"
data-wp-context Lokalno reaktivno stanje za vsak primerek data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Oskrbovalnik dogodka data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Poveži atribut HTML data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Preklopi razred CSS data-wp-class--is-active="context.isActive"
data-wp-text Nastavi besedilno vsebino data-wp-text="state.count"
data-wp-style--[prop] Nastavi vgrajeni slog data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Globalni dogodek dokumenta data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Zaženi povratni klic ob spremembi stanja data-wp-watch="callbacks.log"
data-wp-each Pojdi skozi polje data-wp-each="state.items"

Shramba

Vsak interaktivni blok ima shrambo, ki jo ustvarite s klicem store() z imenskim prostorom in objektom, ki vsebuje actions, callbacks in po želji state:

JavaScript
import { store, getContext } from '@wordpress/interactivity';

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

Znotraj dejanj getContext() vrne najbližji objekt data-wp-context v drevesu DOM. getElement() vrne sklic na element DOM, ki je sprožil dejanje, kar je uporabno za branje atributov data-*.

Kontekst in stanje

Kontekst (data-wp-context) je lokalen za vsak primerek bloka. Če na stran postavite tri harmonike, ima vsak svojo vrednost isOpen. Preklop enega ne vpliva na druge.

Stanje (wp_interactivity_state()) je globalno in v skupni rabi med vsemi primerki bloka. Uporabite ga za podatke s strežnika (na primer število komentarjev) ali vrednosti, ki morajo biti povsod enake.

Kontekst deluje tako v urejevalniku kot na frontendu. Stanje je na voljo samo na frontendu, ker ga WordPress serializira v oznako skripta, ki ni vključena v odzive urejevalnika REST API.

Harmonika

Najpreprostejši interaktivni vzorec: kliknite gumb in preklopite prikaz vsebine. Ta primer potrebuje le tri direktive in nekaj vrstic 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;
    },
  },
});

Kako deluje:

  1. data-wp-context='{ "isOpen": false }' ustvari lokalno logično vrednost za ta primerek.
  2. Klik gumba pokliče actions.toggle, ki preklopi context.isOpen.
  3. data-wp-bind--hidden="!context.isOpen" skrije ali prikaže ploščo.
  4. data-wp-bind--aria-expanded in data-wp-text posodobita stanje gumba za dostopnost in vizualni indikator.

Ker vsak primerek bloka dobi svoj kontekst, lahko na stran brez dodatnih nastavitev postavite več harmonik. Preklapljajo se neodvisno.

Zavihki

Zavihki uvedejo dva nova koncepta: data-wp-class--* za preklapljanje razredov CSS in getElement() za branje podatkovnih atributov elementa, ki je sprožil dejanje.

Ta primer uporablja ponavljajoče se polje, da lahko uredniki dodajo poljubno število zavihkov.

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);
}

Kaj je novega:

  • getElement() vrne { ref }, kjer je ref element DOM. Preberemo data-index, da ugotovimo, kateri zavihek je bil kliknjen. Tako ni treba ustvariti ločenega dejanja za vsak zavihek.
  • callbacks so izpeljane vrednosti, ki se znova ovrednotijo ob spremembi konteksta. Gumbi zavihkov in plošče uporabljajo callbacks.isActiveTab, da preverijo, ali se njihov indeks ujema z context.activeTab.
  • data-wp-class--is-active-tab doda ali odstrani razred is-active-tab glede na vrednost, ki jo vrne povratni klic.

Modalno okno uporablja obravnavo dogodkov na ravni dokumenta z data-wp-on-document--keydown za zapiranje s tipko Escape in zapiranje s klikom na ozadje. Prikazuje tudi pravilne atribute dostopnosti za pogovorno okno.

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;
      }
    },
  },
});

Kaj je novega:

  • data-wp-on-document--keydown posluša na document namesto na samem elementu. Oskrbovalnik se sproži ne glede na to, kateri element ima fokus, zato Escape deluje od koder koli.
  • Zapiranje s klikom na ozadje uporablja dve plasti: prekrivni element div pokliče actions.backdropClick, notranje pogovorno okno pa pokliče actions.stopPropagation, da kliki znotraj njega ne povzročijo zapiranja.
  • role="dialog" in aria-modal="true" bralnikom zaslona sporočita, da gre za modalno pogovorno okno. aria-label je vezan tako, da velja samo, ko je modalno okno vidno.
  • Atribut hidden na prekrivnem elementu skrije modalno okno in prepreči sprožitev poslušalnika dogodkov keydown v dokumentu, ko je okno zaprto, saj so direktive na skritih elementih začasno ustavljene.

Gumb »Všeč mi je« s stanjem s strežnika

Ta primer združuje stanje na strani strežnika z dejanji na strani odjemalca. Število všečkov se inicializira iz PHP z uporabo wp_interactivity_state(), gumb pa ga posodobi ob kliku.

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;
}

Kaj je novega:

  • wp_interactivity_state() inicializira število iz PHP. Vrednost se serializira v HTML strani in je v direktivah ter state.count na voljo kot JavaScript.
  • state v primerjavi z context: število je v state (globalno, v skupni rabi), medtem ko je liked v context (za vsak primerek posebej). Če bi za isti element uporabili več gumbov »Všeč mi je«, bi si delili število, vsak pa bi lahko spremljal svoje stanje všečkanja.
  • Razčlenitev vrednosti iz store(): klic store() vrne reaktivni objekt state, na katerega se lahko sklicujete v dejanjih.

Pomembna omejitev: Stanje s strežnika je na voljo samo na frontendu. V urejevalniku se blok izriše prek REST API, zato wp_interactivity_state() ni vključeno. Nadomestno besedilo, izrisano z PHP (<?php echo esc_html( $count ); ?>), je prikazano kot začetna vrednost v predogledu urejevalnika. Za interaktivno stanje v urejevalniku uporabite data-wp-context.

Nasveti in vzorci

Dogovori o imenih. Kot predpono uporabite ime teme ali vtičnika: myTheme/accordion, myPlugin/tabs. Tako preprečite trke, kadar več blokov na isti strani uporablja API Interactivity.

Korak gradnje ni potreben. Blockstudio naloži script.js kot izvorni modul ES in samodejno ustvari importmap za @wordpress/interactivity. Pišete običajni JavaScript z ukazi import in vse deluje takoj.

Bloki samo z direktivami. Če vaš blok uporablja samo data-wp-context z data-wp-bind--hidden ali data-wp-text, datoteke script.js sploh ne potrebujete. Interactivity API to obravnava deklarativno. Zgornji primer harmonike bi lahko deloval brez JavaScript, če bi uporabili trik s potrditvenim poljem, vendar je pristop s skriptom čistejši.

Odpravljanje napak z data-wp-watch. Med razvojem dodajte povratni klic za spremljanje, da beležite spremembe konteksta:

JavaScript
store('myBlock', {
  callbacks: {
    debug: () => {
      const context = getContext();
      console.log('context changed:', { ...context });
    },
  },
});
HTML
<div data-wp-watch="callbacks.debug" ...>

Pred izdajo ga odstranite.

Kontekst naj bo čim manjši. V data-wp-context dodajte samo vrednosti, ki se dejansko spreminjajo. Statični podatki, kot so oznake in vsebina, naj ostanejo v PHP. Kontekst JSON se serializira v vsak primerek bloka, zato veliki objekti povečajo velikost strani.

Naslednji koraki

  • Referenca Interactivity: možnosti konfiguracije, podrobnosti o podpori v urejevalniku in objektna oblika nastavitve interactivity.
  • Sredstva: kako Blockstudio nalaga script.js, style.css in druga sredstva blokov.
  • WordPress dokumentacija za Interactivity API: celotna referenca za API, vključno z data-wp-each, data-wp-init, data-wp-run in drugimi direktivami, ki v tem vodniku niso zajete.