Preskočiť na obsah

Tvorba interaktívnych komponentov

Bloky WordPress sú predvolene statické. Editor ukladá HTML do databázy, frontend ho vykreslí a tým sa príbeh končí. Pri mnohých blokoch je to presne tak, ako má byť. Niektoré komponenty však musia reagovať na interakciu používateľa: prepínať obsah, meniť karty, otvárať dialógy či aktualizovať počítadlá.

WordPress Interactivity API pridáva blokom reaktívne správanie na strane klienta pomocou atribútov HTML nazývaných direktívy. Namiesto addEventListener píšete data-wp-on--click a namiesto element.hidden = true píšete data-wp-bind--hidden. API sa automaticky postará o reaktivitu, izoláciu kontextu a hydratáciu.

Blockstudio zabezpečuje prepojenie. Nastavte "interactivity": true vo svojom block.json a Blockstudio vygeneruje importmap, načíta API v editore aj na frontende a vyrieši importy modulov ES. Bez zostavovania, bez bundlera, bez konfigurácie webpacku. Podrobnosti o konfigurácii nájdete v referencii Interactivity.

Táto príručka vás prevedie štyrmi kompletnými komponentmi, z ktorých každý predstavuje nové koncepty. Na konci budete mať funkčné vzory pre najbežnejšie interaktívne prvky UI.

Ako to funguje

Direktívy

Direktívy sú atribúty data-wp-*, ktoré deklarujú reaktívne správanie priamo vo vašom HTML. Najčastejšie používané:

Direktíva Účel Príklad
data-wp-interactive Definuje menný priestor úložiska data-wp-interactive="myBlock"
data-wp-context Lokálny reaktívny stav pre každú inštanciu data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Obsluha udalosti data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Naviaže atribút HTML data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Prepína triedu CSS data-wp-class--is-active="context.isActive"
data-wp-text Nastaví textový obsah data-wp-text="state.count"
data-wp-style--[prop] Nastaví vnorený štýl data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Globálna udalosť dokumentu data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Spustí spätné volanie pri zmene stavu data-wp-watch="callbacks.log"
data-wp-each Prechádza prvky poľa data-wp-each="state.items"

Úložisko

Každý interaktívny blok má úložisko, ktoré vytvoríte zavolaním store() s menným priestorom a objektom obsahujúcim actions, callbacks a prípadne state:

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

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

V akciách funkcia getContext() vráti najbližší objekt data-wp-context v strome DOM. Funkcia getElement() vráti odkaz na prvok DOM, ktorý akciu vyvolal, čo je užitočné pri čítaní atribútov data-*.

Kontext a stav

Kontext (data-wp-context) je lokálny pre každú inštanciu bloku. Ak na stránku umiestnite tri akordeóny, každý má vlastnú hodnotu isOpen. Prepnutie jedného neovplyvní ostatné.

Stav (wp_interactivity_state()) je globálny a zdieľa sa medzi všetkými inštanciami bloku. Použite ho pre údaje zo servera, napríklad počet komentárov, alebo pre hodnoty, ktoré majú byť všade rovnaké.

Kontext funguje v editore aj na frontende. Stav je dostupný iba na frontende, pretože WordPress ho serializuje do značky script, ktorá nie je súčasťou odpovedí REST API editora.

Akordeón

Najjednoduchší interaktívny vzor: kliknete na tlačidlo a prepnete obsah. Tento príklad potrebuje iba tri direktívy a niekoľko riadkov 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;
    },
  },
});

Ako to funguje:

  1. data-wp-context='{ "isOpen": false }' vytvorí pre túto inštanciu lokálnu logickú hodnotu.
  2. Kliknutie na tlačidlo zavolá actions.toggle, ktoré prepne hodnotu context.isOpen.
  3. data-wp-bind--hidden="!context.isOpen" skryje alebo zobrazí panel.
  4. data-wp-bind--aria-expanded a data-wp-text aktualizujú stav tlačidla pre prístupnosť aj vizuálny indikátor.

Keďže každá inštancia bloku má vlastný kontext, na stránke môžete bez ďalšieho nastavovania umiestniť viac akordeónov. Prepínajú sa nezávisle.

Karty

Karty predstavujú dva nové koncepty: data-wp-class--* na prepínanie tried CSS a getElement() na čítanie dátových atribútov prvku, ktorý vyvolal akciu.

Tento príklad používa opakovacie pole, aby mohli editori pridať ľubovoľný počet kariet.

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

Čo je tu nové:

  • getElement() vráti { ref }, v ktorom ref označuje prvok DOM. Hodnotu data-index čítame, aby sme zistili, na ktorú kartu sa kliklo. Vďaka tomu netreba vytvárať samostatnú akciu pre každú kartu.
  • callbacks sú odvodené hodnoty, ktoré sa prepočítajú pri zmene kontextu. Tlačidlá kariet aj panely používajú callbacks.isActiveTab na kontrolu, či sa ich index zhoduje s context.activeTab.
  • data-wp-class--is-active-tab pridáva alebo odstraňuje triedu is-active-tab podľa návratovej hodnoty spätného volania.

Modálne okno predstavuje obsluhu udalostí na úrovni dokumentu pomocou data-wp-on-document--keydown, ktoré ho zatvorí po stlačení Escape, a zatvorenie kliknutím na pozadie. Ukazuje tiež správne atribúty prístupnosti dialógu.

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

Čo je tu nové:

  • data-wp-on-document--keydown počúva na document namiesto samotného prvku. Obsluha sa spustí bez ohľadu na to, ktorý prvok má zameranie, takže Escape funguje odkiaľkoľvek.
  • Zatvorenie kliknutím na pozadie používa dve vrstvy: prekryvný prvok div zavolá actions.backdropClick, zatiaľ čo vnútorný dialóg zavolá actions.stopPropagation, aby zabránil zatvoreniu pri kliknutí dovnútra dialógu.
  • role="dialog" a aria-modal="true" oznamujú čítačkám obrazovky, že ide o modálny dialóg. aria-label je naviazaný tak, aby sa uplatnil iba vtedy, keď je modálne okno viditeľné.
  • Atribút hidden na prekryvnom prvku modálne okno skryje a zároveň zabráni spusteniu poslucháča udalosti keydown dokumentu, keď je okno zatvorené, pretože direktívy na skrytých prvkoch sú pozastavené.

Tlačidlo Páči sa mi to so stavom zo servera

Tento príklad kombinuje stav na strane servera s akciami na strane klienta. Počet označení Páči sa mi to sa inicializuje z PHP pomocou wp_interactivity_state() a tlačidlo ho aktualizuje po kliknutí.

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

Čo je tu nové:

  • wp_interactivity_state() inicializuje počet z PHP. Hodnota sa serializuje do HTML stránky a v direktívach a JavaScript je dostupná ako state.count.
  • state a context: počet je v state (globálny, zdieľaný), zatiaľ čo liked je v context (pre každú inštanciu zvlášť). Ak by ste mali viac tlačidiel Páči sa mi to pre tú istú položku, zdieľali by počet, ale každé by mohlo sledovať vlastný stav označenia Páči sa mi to.
  • Rozbalenie z store(): volanie store() vráti reaktívny objekt state, na ktorý sa môžete odkazovať vo svojich akciách.

Dôležité upozornenie: Stav zo servera je dostupný iba na frontende. V editore sa blok vykresľuje prostredníctvom REST API, takže wp_interactivity_state() nie je zahrnutý. Náhradný text vykreslený pomocou PHP (<?php echo esc_html( $count ); ?>) sa v náhľade editora zobrazí ako počiatočná hodnota. Ak chcete interaktívny stav editora, použite namiesto toho data-wp-context.

Tipy a vzory

Konvencie pre menné priestory. Ako predponu použite názov témy alebo pluginu: myTheme/accordion, myPlugin/tabs. Predídete tak kolíziám, keď viacero blokov na tej istej stránke používa Interactivity API.

Zostavovanie nie je potrebné. Blockstudio načíta script.js ako natívny modul ES a automaticky vygeneruje importmap pre @wordpress/interactivity. Píšete štandardný JavaScript s príkazmi import a funguje to okamžite.

Bloky používajúce iba direktívy. Ak váš blok používa iba data-wp-context s data-wp-bind--hidden alebo data-wp-text, vôbec nepotrebujete script.js. Interactivity API ich spracuje deklaratívne. Vyššie uvedený príklad akordeónu by fungoval aj bez JavaScript, ak by ste použili trik s zaškrtávacím políčkom, no prístup so skriptom je prehľadnejší.

Ladenie pomocou data-wp-watch. Počas vývoja pridajte spätné volanie watch, ktoré bude zaznamenávať zmeny kontextu:

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

Pred nasadením ho odstráňte.

Kontext udržiavajte stručný. Do data-wp-context vkladajte iba hodnoty, ktoré sa skutočne menia. Statické údaje, ako sú označenia a obsah, ponechajte v PHP. Kontext JSON sa serializuje do každej inštancie bloku, takže veľké objekty zväčšujú stránku.

Ďalšie kroky

  • Referencia Interactivity: možnosti konfigurácie, podrobnosti o podpore editora a objektová forma nastavenia interactivity.
  • Prostriedky: ako Blockstudio načítava script.js, style.css a ďalšie prostriedky blokov.
  • WordPress dokumentácia Interactivity API: úplná referencia API vrátane data-wp-each, data-wp-init, data-wp-run a ďalších direktív, ktoré táto príručka nepokrýva.