Перейти до вмісту

Створення інтерактивних компонентів

WordPress блоки за замовчуванням статичні. Редактор зберігає HTML у базі даних, фронтенд відображає його — на цьому все. Для багатьох блоків це саме те, що потрібно. Але деякі компоненти мають реагувати на взаємодію з користувачем: перемикати вміст, перемикати вкладки, відкривати діалогові вікна, оновлювати лічильники.

WordPress Interactivity API додає блокам реактивну поведінку на боці клієнта за допомогою атрибутів HTML, які називаються директивами. Замість addEventListener ви пишете data-wp-on--click, а замість element.hidden = true — data-wp-bind--hidden. API автоматично обробляє реактивність, ізоляцію контексту й гідратацію.

Blockstudio бере на себе налаштування зв’язків. Укажіть "interactivity": true у своєму block.json, і Blockstudio створить importmap, завантажить API і в редакторі, і на фронтенді та розв’яже імпорти ES-модулів. Без етапу збірки, без збирача, без конфігурації webpack. Докладніше про налаштування читайте в довіднику з Interactivity.

У цьому посібнику розглянуто чотири повноцінні компоненти, кожен із новими поняттями. Наприкінці у вас будуть готові до використання шаблони найпоширеніших інтерактивних елементів UI.

Як це працює

Директиви

Директиви — це атрибути data-wp-*, які безпосередньо в HTML визначають реактивну поведінку. Найуживаніші з них:

Директива Призначення Приклад
data-wp-interactive Визначає простір імен сховища data-wp-interactive="myBlock"
data-wp-context Локальний реактивний стан для кожного екземпляра data-wp-context='{ "isOpen": false }'
data-wp-on--[event] Обробник події data-wp-on--click="actions.toggle"
data-wp-bind--[attr] Прив’язує атрибут HTML data-wp-bind--hidden="!context.isOpen"
data-wp-class--[name] Перемикає клас CSS data-wp-class--is-active="context.isActive"
data-wp-text Установлює текстовий вміст data-wp-text="state.count"
data-wp-style--[prop] Установлює вбудований стиль data-wp-style--opacity="context.opacity"
data-wp-on-document--[event] Глобальна подія документа data-wp-on-document--keydown="actions.onKeydown"
data-wp-watch Виконує зворотний виклик у разі зміни стану data-wp-watch="callbacks.log"
data-wp-each Перебирає масив data-wp-each="state.items"

Сховище

Кожен інтерактивний блок має сховище, створене викликом store() із простором імен та об’єктом, що містить actions, callbacks і, за бажанням, state:

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

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

Усередині дій getContext() повертає найближчий об’єкт data-wp-context у дереві DOM. getElement() повертає посилання на елемент DOM, який запустив дію; це зручно для читання атрибутів data-*.

Контекст і стан

Контекст (data-wp-context) є локальним для кожного екземпляра блока. Якщо розмістити на сторінці три акордеони, кожен матиме власне значення isOpen. Перемикання одного не вплине на інші.

Стан (wp_interactivity_state()) є глобальним і спільним для всіх екземплярів блока. Використовуйте його для даних із сервера (наприклад, кількості коментарів) або значень, які мають бути однаковими всюди.

Контекст працює і в редакторі, і на фронтенді. Стан доступний лише на фронтенді, оскільки WordPress серіалізує його в тег script, якого немає у відповідях REST API редактора.

Акордеон

Найпростіший інтерактивний шаблон: натиснути кнопку й перемкнути вміст. Для цього прикладу потрібні лише три директиви та кілька рядків 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;
    },
  },
});

Як це працює:

  1. data-wp-context='{ "isOpen": false }' створює локальне логічне значення для цього екземпляра.
  2. Натискання кнопки викликає actions.toggle, яка перемикає context.isOpen.
  3. data-wp-bind--hidden="!context.isOpen" приховує або показує панель.
  4. data-wp-bind--aria-expanded і data-wp-text оновлюють стан кнопки для доступності та візуального індикатора.

Оскільки кожен екземпляр блока має власний контекст, кілька акордеонів на сторінці працюють одразу й перемикаються незалежно один від одного.

Вкладки

Вкладки вводять два нові поняття: data-wp-class--* для перемикання класів CSS і getElement() для читання атрибутів даних елемента, який запустив дію.

У цьому прикладі використовується поле з повторюваними елементами, щоб редактори могли додати потрібну кількість вкладок.

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

Що тут нового:

  • getElement() повертає { ref }, де ref — це елемент DOM. Ми читаємо data-index, щоб визначити, яку вкладку натиснули. Так не потрібно створювати окрему дію для кожної вкладки.
  • callbacks — це похідні значення, які переобчислюються зі зміною контексту. Кнопки вкладок і панелі використовують callbacks.isActiveTab, щоб перевірити, чи збігається їхній індекс із context.activeTab.
  • data-wp-class--is-active-tab додає або видаляє клас is-active-tab залежно від значення, поверненого зворотним викликом.

У прикладі з модальним вікном показано обробку подій на рівні документа за допомогою data-wp-on-document--keydown для закриття клавішею Escape, а також закриття натисканням на тло. Також показано правильні атрибути доступності діалогового вікна.

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

Що тут нового:

  • data-wp-on-document--keydown слухає події на document, а не на самому елементі. Обробник спрацьовує незалежно від того, який елемент має фокус, тому Escape працює звідусіль.
  • Закриття натисканням на тло реалізовано у два шари: зовнішній div викликає actions.backdropClick, а внутрішнє діалогове вікно викликає actions.stopPropagation, щоб натискання всередині вікна не закривало його.
  • role="dialog" і aria-modal="true" повідомляють програмам читання з екрана, що це модальне діалогове вікно. Прив’язка aria-label забезпечує його застосування лише тоді, коли модальне вікно видиме.
  • Атрибут hidden зовнішнього елемента і приховує модальне вікно, і не дає слухачеві події keydown документа спрацьовувати, коли вікно закрите, адже директиви на прихованих елементах призупиняються.

Кнопка вподобання зі станом сервера

У цьому прикладі поєднано стан на боці сервера з діями на боці клієнта. Кількість вподобань ініціалізується з PHP за допомогою wp_interactivity_state(), а кнопка оновлює її після натискання.

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

Що тут нового:

  • wp_interactivity_state() ініціалізує кількість із PHP. Значення серіалізується у HTML сторінки й доступне як state.count у директивах і JavaScript.
  • state і context: кількість зберігається в state (глобальному, спільному), а liked — у context (для кожного екземпляра окремо). Якщо на той самий елемент було б кілька кнопок уподобання, вони мали б спільну кількість, але кожна могла б окремо відстежувати статус уподобання.
  • Деструктуризація з store(): виклик store() повертає реактивний об’єкт state, на який можна посилатися у своїх діях.

Важливе застереження: стан сервера доступний лише на фронтенді. У редакторі блок відображається через REST API, тому wp_interactivity_state() не включається. Текст-заповнювач PHP (<?php echo esc_html( $count ); ?>) показується як початкове значення в попередньому перегляді редактора. Для інтерактивного стану в редакторі використовуйте data-wp-context.

Поради та шаблони

Угоди щодо просторів імен. Використовуйте назву теми або плагіна як префікс: myTheme/accordion, myPlugin/tabs. Це запобігає конфліктам, якщо кілька блоків на одній сторінці використовують Interactivity API.

Етап збірки не потрібен. Blockstudio завантажує script.js як нативний ES-модуль і автоматично створює importmap для @wordpress/interactivity. Ви пишете звичайний JavaScript із виразами import, і все працює одразу.

Блоки лише з директивами. Якщо блок використовує тільки data-wp-context з data-wp-bind--hidden або data-wp-text, script.js узагалі не потрібен. Interactivity API обробляє це декларативно. Наведений вище приклад акордеона міг би працювати без JavaScript із трюком із прапорцем, але підхід зі скриптом чистіший.

Налагодження за допомогою data-wp-watch. Додайте зворотний виклик watch, щоб під час розробки записувати зміни контексту до журналу:

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

Видаліть його перед випуском.

Зводьте контекст до мінімуму. Додавайте в data-wp-context лише значення, які справді змінюються. Статичні дані, як-от мітки й вміст, мають залишатися в PHP. Контекст JSON серіалізується для кожного екземпляра блока, тож великі об’єкти збільшують розмір сторінки.

Наступні кроки

  • Довідник з Interactivity: параметри конфігурації, підтримка редактора та об’єктний формат параметра interactivity.
  • Ресурси: як Blockstudio завантажує script.js, style.css та інші ресурси блоків.
  • ДокументаціяWordPress Interactivity API: повний довідник API, зокрема про data-wp-each, data-wp-init, data-wp-run та інші директиви, не розглянуті в цьому посібнику.