Изграждане на интерактивни компоненти
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 го сериализира в скриптов етикет, който не присъства в отговорите 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. Това предотвратява конфликти, когато няколко блока на една страница използват API Interactivity.
Не е необходима стъпка за изграждане. 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. Добавете обратна функция за наблюдение, която записва промените в контекста по време на разработка:
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и други активи на блокове. - Документация за Interactivity на WordPress API: пълната справка за API, включително
data-wp-each,data-wp-init,data-wp-runи други директиви, които не са разгледани в това ръководство.