Към съдържанието

Изграждане на интерактивни компоненти

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 го сериализира в скриптов етикет, който не присъства в отговорите 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. Това предотвратява конфликти, когато няколко блока на една страница използват 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. Добавете обратна функция за наблюдение, която записва промените в контекста по време на разработка:

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