Создание интерактивных компонентов
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:
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.
{
"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." }
]
}
}
<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>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/accordion', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Как это работает:
data-wp-context='{ "isOpen": false }'создаёт локальное логическое значение для этого экземпляра.- Нажатие кнопки вызывает
actions.toggle, которое переключаетcontext.isOpen. data-wp-bind--hidden="!context.isOpen"скрывает или показывает панель.data-wp-bind--aria-expandedиdata-wp-textобновляют состояние кнопки для доступности и визуального индикатора.
Поскольку у каждого экземпляра блока свой контекст, несколько аккордеонов на странице работают сразу после добавления. Они переключаются независимо друг от друга.
Вкладки
Вкладки знакомят с двумя новыми понятиями: data-wp-class--* для переключения классов CSS и getElement() для чтения атрибутов данных элемента, запустившего действие.
В этом примере используется поле-повторитель, чтобы редакторы могли добавлять сколько угодно вкладок.
{
"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." }
]
}
]
}
}
<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>
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);
},
},
});
.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, а щелчок по фону также закрывает его. Кроме того, показаны нужные атрибуты доступности диалога.
{
"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." }
]
}
}
<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>
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(), а при нажатии кнопки обновляется.
{
"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
$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>
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++;
}
},
},
});
.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 наблюдения, чтобы во время разработки записывать изменения контекста в журнал:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<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и другие директивы, не рассмотренные в этом руководстве.