Перейти к содержимому

Создание интерактивных компонентов

WordPress по умолчанию статичны. Редактор сохраняет HTML в базу данных, фронтенд отображает их — и на этом всё. Для многих блоков этого вполне достаточно. Но некоторые компоненты должны реагировать на действия пользователя: переключать содержимое и вкладки, открывать диалоги, обновлять счётчики.

WordPress Interactivity API добавляет блокам реактивное поведение на стороне клиента с помощью атрибутов HTML, называемых директивами. Вместо data-wp-on--click вы пишете addEventListener, вместо data-wp-bind--hidden — element.hidden = true. 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 при использовании приёма с checkbox, но вариант со скриптом чище.

Отладка с помощью data-wp-watch. Добавьте callback наблюдения, чтобы во время разработки записывать изменения контекста в журнал:

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 и другие директивы, не рассмотренные в этом руководстве.