构建交互组件
WordPress区块默认是静态的。编辑器会将 HTML保存到数据库,前端负责渲染,整个流程就结束了。对许多区块来说,这完全没问题。但有些组件需要响应用户交互:切换内容、切换标签页、打开对话框、更新计数器。
WordPress Interactivity API通过称为指令的 HTML属性,为区块添加响应式客户端行为。使用 data-wp-on--click而不是 addEventListener,使用 data-wp-bind--hidden而不是 element.hidden = true。API会自动处理响应性、上下文隔离和水合。
Blockstudio负责处理连接配置。在 block.json中设置 "interactivity": true后,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()会返回 DOM 树中最近的 data-wp-context对象。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 监听器触发,因为隐藏元素上的指令会暂停。
带服务器状态的点赞按钮
此示例将服务器端状态与客户端操作结合起来。点赞数使用 wp_interactivity_state()从 PHP初始化,点击按钮时会更新。
{
"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中,并可在指令和 JavaScript中作为state.count使用。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 模块加载,并自动为 @wordpress/interactivity生成 importmap。你只需编写带有 import语句的标准 JavaScript,即可立即使用。
仅使用指令的区块。 如果区块只将 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和其他区块资源。 - WordPress Interactivity API文档:完整的 API参考,包括本指南未涵盖的
data-wp-each、data-wp-init、data-wp-run和其他指令。