Přejít k obsahu

Tvorba interaktivních komponent

WordPress bloky jsou ve výchozím nastavení statické. Editor ukládá HTML do databáze, frontend je vykreslí a tím to končí. U mnoha bloků je to přesně tak správně. Některé komponenty ale musí reagovat na interakci uživatele: přepínat obsah, měnit karty, otevírat dialogová okna nebo aktualizovat počítadla.

WordPress Interactivity API přidává blokům reaktivní chování na straně klienta pomocí atributů HTML zvaných direktivy. Píšete data-wp-on--click místo addEventListener a data-wp-bind--hidden místo element.hidden = true. API automaticky zajišťuje reaktivitu, izolaci kontextu a hydrataci.

Blockstudio zajišťuje propojení. Nastavte "interactivity": true ve svém block.json a Blockstudio vygeneruje importmap, načte API v editoru i na frontendu a vyřeší importy modulů ES. Žádné sestavování, žádný bundler ani konfigurace webpacku. Podrobnosti o konfiguraci najdete v referenci Interactivity.

Tento průvodce vás provede čtyřmi kompletními komponentami, z nichž každá představí nové koncepty. Na konci budete mít funkční vzory pro nejběžnější interaktivní prvky UI.

Jak to funguje

Direktivy

Direktivy jsou atributy data-wp-*, které deklarují reaktivní chování přímo ve vašem HTML. Nejčastěji se používají tyto:

Direktiva Účel Příklad
data-wp-interactive Definuje jmenný prostor úložiště data-wp-interactive="myBlock"
data-wp-context Lokální reaktivní stav pro každou instanci data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Obsluha události data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Naváže atribut HTML data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Přepíná třídu CSS data-wp-class--is-active="context.isActive"
data-wp-text Nastaví textový obsah data-wp-text="state.count"
data-wp-style--[prop] Nastaví vložený styl data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Globální událost dokumentu data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Spustí zpětné volání při změně stavu data-wp-watch="callbacks.log"
data-wp-each Prochází pole data-wp-each="state.items"

Úložiště

Každý interaktivní blok má úložiště, které vzniká voláním store() se jmenným prostorem a objektem obsahujícím actions, callbacks a případně state:

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

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

Uvnitř akcí vrací getContext() nejbližší objekt data-wp-context ve stromu DOM směrem nahoru. getElement() vrací odkaz na prvek DOM, který akci vyvolal; hodí se pro čtení atributů data-*.

Kontext a stav

Kontext (data-wp-context) je lokální pro každou instanci bloku. Pokud na stránku vložíte tři akordeony, každý bude mít vlastní hodnotu isOpen. Přepnutí jednoho neovlivní ostatní.

Stav (wp_interactivity_state()) je globální a sdílený mezi všemi instancemi bloku. Použijte jej pro data pocházející ze serveru (například počet komentářů) nebo hodnoty, které mají být všude stejné.

Kontext funguje v editoru i na frontendu. Stav je dostupný pouze na frontendu, protože WordPress jej serializuje do značky script, která není součástí odpovědí REST API editoru.

Akordeon

Nejjednodušší interaktivní vzor: kliknutím na tlačítko přepnete obsah. Tento příklad vyžaduje jen tři direktivy a několik řádků 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;
    },
  },
});

Jak to funguje:

  1. data-wp-context='{ "isOpen": false }' vytvoří pro tuto instanci lokální logickou hodnotu.
  2. Kliknutím na tlačítko zavoláte actions.toggle, které přepne context.isOpen.
  3. data-wp-bind--hidden="!context.isOpen" panel skryje nebo zobrazí.
  4. data-wp-bind--aria-expanded a data-wp-text aktualizují stav tlačítka kvůli přístupnosti a vizuálnímu ukazateli.

Každá instance bloku má vlastní kontext, takže na stránku můžete bez dalších úprav vložit více akordeonů. Přepínají se nezávisle.

Karty

Karty představují dva nové koncepty: data-wp-class--* pro přepínání tříd CSS a getElement() pro čtení datových atributů prvku, který akci vyvolal.

Tento příklad používá opakovací pole, aby mohli editoři přidat libovolný počet karet.

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

Co je zde nového:

  • getElement() vrací { ref }, kde ref je prvek DOM. Zjišťujeme data-index, abychom poznali, na kterou kartu uživatel klikl. Díky tomu nemusíme vytvářet samostatnou akci pro každou kartu.
  • callbacks jsou odvozené hodnoty, které se přepočítají při změně kontextu. Tlačítka karet i panely pomocí callbacks.isActiveTab kontrolují, zda se jejich index shoduje s context.activeTab.
  • data-wp-class--is-active-tab přidává nebo odebírá třídu is-active-tab podle návratové hodnoty zpětného volání.

Modální okno představuje obsluhu událostí na úrovni dokumentu pomocí data-wp-on-document--keydown, které ho zavře po stisknutí Escape, a zavírání kliknutím na pozadí. Ukazuje také správné atributy přístupnosti dialogového okna.

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

Co je zde nového:

  • data-wp-on-document--keydown naslouchá na document místo na samotném prvku. Obsluha se spustí bez ohledu na to, který prvek má fokus, takže Escape funguje odkudkoli.
  • Zavření kliknutím na pozadí využívá dvě vrstvy: překryvný prvek div zavolá actions.backdropClick, zatímco vnitřní dialog zavolá actions.stopPropagation, aby kliknutí uvnitř dialogu nezpůsobilo jeho zavření.
  • role="dialog" a aria-modal="true" sdělují čtečkám obrazovky, že jde o modální dialog. aria-label je navázán tak, aby se uplatnil pouze při zobrazeném modálním okně.
  • Atribut hidden na překryvné vrstvě modální okno skryje a zabrání spuštění posluchače události keydown na dokumentu, když je okno zavřené, protože direktivy na skrytých prvcích jsou pozastaveny.

Tlačítko To se mi líbí se stavem ze serveru

Tento příklad kombinuje stav na straně serveru s akcemi na straně klienta. Počet označení „To se mi líbí“ se inicializuje z PHP pomocí wp_interactivity_state() a tlačítko jej 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;
}

Co je zde nového:

  • wp_interactivity_state() inicializuje počet z PHP. Hodnota se serializuje do HTML stránky a je dostupná jako state.count v direktivách a JavaScript.
  • state a context: počet je v state (globální, sdílený), zatímco liked je v context (pro každou instanci zvlášť). Pokud byste měli několik tlačítek „To se mi líbí“ pro stejnou položku, sdílela by počet, ale každé by mohlo samostatně sledovat, zda se vám položka líbí.
  • Destrukturování z store(): volání store() vrací reaktivní objekt state, na který se můžete odkazovat ve svých akcích.

Důležité upozornění: Stav ze serveru je dostupný pouze na frontendu. V editoru se blok vykresluje pomocí REST API, takže wp_interactivity_state() není zahrnut. Náhradní text vykreslený pomocí PHP (<?php echo esc_html( $count ); ?>) se zobrazí jako počáteční hodnota v náhledu editoru. Pro interaktivní stav v editoru použijte místo toho data-wp-context.

Tipy a vzory

Konvence jmenných prostorů. Jako předponu používejte název šablony nebo pluginu: myTheme/accordion, myPlugin/tabs. Zabráníte tak kolizím, když více bloků na stejné stránce používá API Interactivity.

Sestavení není potřeba. Blockstudio načítá script.js jako nativní modul ES a automaticky generuje importmap pro @wordpress/interactivity. Píšete standardní JavaScript s příkazy import a vše funguje okamžitě.

Bloky pouze s direktivami. Pokud váš blok používá jen data-wp-context s data-wp-bind--hidden nebo data-wp-text, soubor script.js vůbec nepotřebujete. API Interactivity se o tyto deklarativní prvky postará. Výše uvedený příklad akordeonu by fungoval i bez JavaScript, kdybyste použili trik s checkboxem, ale řešení pomocí skriptu je čistší.

Ladění pomocí data-wp-watch. Při vývoji přidejte zpětné volání watch, které bude zaznamenávat změny kontextu:

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

Před nasazením ho odeberte.

Udržujte kontext co nejmenší. Do data-wp-context vkládejte jen hodnoty, které se skutečně mění. Statická data, jako jsou popisky a obsah, ponechte v PHP. Kontext JSON se serializuje do každé instance bloku, takže velké objekty zvětšují stránku.

Další kroky

  • Reference Interactivity: možnosti konfigurace, podrobnosti o podpoře editoru a objektová podoba nastavení interactivity.
  • Prostředky: jak Blockstudio načítá script.js, style.css a další prostředky bloků.
  • Dokumentace WordPress Interactivity API: úplná referenční příručka API včetně data-wp-each, data-wp-init, data-wp-run a dalších direktiv, které tento průvodce nepokrývá.