Створення інтерактивних компонентів
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:
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 із трюком із прапорцем, але підхід зі скриптом чистіший.
Налагодження за допомогою data-wp-watch. Додайте зворотний виклик watch, щоб під час розробки записувати зміни контексту до журналу:
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та інші директиви, не розглянуті в цьому посібнику.