WordPress Interactivity API: как делать динамические блоки без тяжёлого frontend-фреймворка

WordPress давно умеет рендерить HTML на сервере, но интерактивность на frontend исторически каждый плагин решал по-своему: jQuery, vanilla JavaScript, React, Vue или собственный набор обработчиков. Interactivity API даёт Core-стандарт для динамических блоков, где серверный HTML остаётся основой, а поведение описывается декларативно через directives и общий store.

API публично доступен разработчикам начиная с WordPress 6.5. Он подходит не только для кнопки «показать/скрыть», но и для фильтров, мгновенного поиска, счётчиков, интерактивных списков и компонентов, которые должны обмениваться состоянием.

Из чего состоит Interactivity API

В официальной документации WordPress модель разделена на две основные части: directives в HTML и store с логикой и данными. Directives связывают DOM с состоянием, context, actions и callbacks.

В markup это выглядит как атрибуты с префиксом data-wp-. Например, data-wp-interactive задаёт namespace, data-wp-on--click связывает событие с action, а data-wp-text выводит реактивное значение.

Почему это не просто ещё один JavaScript-фреймворк

Главное отличие — Interactivity API проектировался вокруг WordPress server-side rendering. PHP формирует исходный HTML, WordPress hooks и переводы уже применены, а клиентский runtime добавляет реактивность поверх готовой разметки.

Это снимает типичную проблему двойного рендера, когда PHP выдаёт один HTML, а React после загрузки строит компонент заново и должен идеально воспроизвести серверную разметку. Официальная документация отдельно подчёркивает совместимость Interactivity API с WordPress hooks и server APIs.

State и context — не одно и то же

Global state нужен, когда данные должны быть доступны разным интерактивным областям одного namespace. Local context относится к конкретному DOM-поддереву и удобен для повторяющихся экземпляров одного блока.

Например, общий счётчик товаров можно хранить в state, а открыто/закрыто конкретное меню — в context экземпляра. Если складывать всё в глобальный state, несколько одинаковых блоков начнут влиять друг на друга без необходимости.

Actions и callbacks

Actions вызываются в ответ на действие пользователя или из другой логики: клик, ввод, навигация. Они могут менять state/context и выполнять обычные JavaScript-операции, включая запросы к API.

Callbacks используются для реактивных побочных эффектов. Они подписываются на используемые значения и запускаются при изменениях. Такой подход удобнее ручного поиска элементов и повторного навешивания event listeners после каждого обновления DOM.

Server-side rendering остаётся первым этапом

В руководстве Server-side rendering WordPress объясняет, что directives могут обрабатываться на сервере до отправки HTML браузеру. Начальное состояние уже отражено в разметке, а JavaScript продолжает работу после загрузки.

Для интерактивного блока в block.json включается поддержка interactivity. Глобальное состояние можно инициализировать через wp_interactivity_state(), а local context — через data-wp-context или helper wp_interactivity_data_wp_context().

Что хранить в config

Config подходит для статических параметров, которые нужны store, но не должны реактивно меняться во время взаимодействия. На сервере для этого есть wp_interactivity_config(). Например, feature flag, endpoint или значение, зависящее от текущего пользователя при начальном рендере.

Не стоит превращать config в замену state. Если значение должно изменяться и обновлять интерфейс, ему место в state/context.

Производительность

В FAQ WordPress указывает, что runtime Interactivity API имеет размер порядка 10 KB и загружается один раз для блоков, использующих этот стандарт. Script modules загружаются без блокировки рендера. На практике итоговая производительность всё равно зависит от вашего кода, количества запросов и объёма данных.

Сам API не исправит медленный REST endpoint или внешний сервис. Если интерактивный блок ждёт сторонний API несколько секунд, нужно диагностировать backend и сеть. Для этого полезен материал про медленные внешние API в WordPress.

Когда Interactivity API особенно полезен

• Кастомный Gutenberg-блок должен менять UI без перезагрузки.
• Несколько блоков обмениваются общим состоянием.
• Нужно сохранить PHP server-side rendering.
• Важно не дублировать разметку между PHP и frontend framework.
• Нужна совместимость с WordPress hooks и переводами.
• Проект постепенно уходит от jQuery.
• Планируется client-side navigation между интерактивными регионами.

Когда обычный JavaScript всё ещё нормален

Для очень маленькой независимой задачи отдельный vanilla JS может быть проще: например, один элемент, который не связан с другими блоками и не требует реактивного состояния. Не нужно переписывать весь frontend только ради использования нового API.

Interactivity API имеет наибольшую ценность, когда компонент действительно является частью block architecture и должен жить в экосистеме WordPress.

Client-side navigation

Современный Interactivity API включает механизмы region-based client-side navigation. При переходе может заменяться часть страницы без полного reload. Здесь важно понимать правила state: клиентские изменения не должны неожиданно затираться серверным состоянием.

Документация предлагает getServerState() и getServerContext(), когда компоненту нужно явно синхронизироваться с данными новой страницы. Это особенно важно для фильтров, результатов поиска и UI, который сохраняет пользовательские переключатели между переходами.

Не смешивайте DOM-мутации без необходимости

Если часть компонента управляется Interactivity API, а другая часть вручную меняет те же DOM-узлы через querySelector и innerHTML, появляется два источника истины. Лучше выражать изменение через state/context и directives.

То же касается CSS-классов: вместо ручного переключения classList используйте декларативные directives, когда состояние уже живёт в store.

Script Modules API

Interactivity API использует современную модульную модель JavaScript. Если проект всё ещё строится вокруг глобальных window.wp.* и старого enqueue-подхода, переход лучше планировать постепенно. Про Script Modules API есть отдельный материал на A.S Groups.

Безопасность запросов остаётся вашей задачей

Action может вызвать REST API или admin-ajax, но Interactivity API не отменяет permissions, nonce и серверную валидацию. Не доверяйте значению только потому, что оно пришло из вашего store. Любое изменение данных на сервере должно проходить обычную WordPress-проверку прав и входных параметров.

Сами directives не предназначены для выполнения произвольных JavaScript-выражений через eval. Это упрощает работу с CSP и снижает класс рисков, связанных с выполнением строкового кода.

Практический порядок разработки

1. Определите, что рендерится PHP и должно быть доступно без ожидания JS.
2. Разделите global state, local context и static config.
3. Опишите DOM-поведение directives вместо ручных мутаций.
4. Вынесите действия пользователя в actions.
5. Добавьте callbacks только для реальных side effects.
6. Проверьте несколько экземпляров блока на одной странице.
7. Проверьте keyboard navigation и accessibility.
8. Измерьте network и JavaScript, а не делайте вывод по ощущениям.

Когда нужна кастомная разработка

Interactivity API особенно интересен для фильтров каталога, конфигураторов, калькуляторов, интерактивных FAQ, поиска и собственных Gutenberg-компонентов. Но архитектуру нужно выбирать по задаче: иногда правильнее Store API WooCommerce, иногда REST endpoint, а иногда вообще достаточно серверного form submit.

A.S Groups разрабатывает кастомные WordPress/Gutenberg-блоки, интеграции и frontend-логику. Обсудить задачу можно через контакты.