交互性
Blockstudio 支持 WordPress 交互性 API,为区块添加响应式客户端行为提供了标准方式。在 block.json 中设置 interactivity,然后由 Blockstudio 负责在前端和编辑器中加载 API。
配置
通过将 API 添加到 block.json 中的 blockstudio 键,即可启用交互性 interactivity:
{
"name": "my-theme/interactive-block",
"title": "Interactive Block",
"category": "text",
"icon": "star-filled",
"description": "A block with interactive behavior.",
"blockstudio": {
"interactivity": true
}
}
你也可以使用对象形式:
{
"blockstudio": {
"interactivity": {
"enqueue": true
}
}
}
两种形式等效。
模板
在区块模板中添加交互性 API 指令。data-wp-interactive 属性定义存储命名空间,其他 data-wp-* 属性则控制响应式行为。
<div useBlockProps
data-wp-interactive="myBlock"
data-wp-context='{ "isOpen": false }'>
<button data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen">
Toggle
</button>
<div data-wp-bind--hidden="!context.isOpen">
This content is toggled by the button.
</div>
</div>
脚本
在区块文件夹中创建一个 script.js 文件,从 @wordpress/interactivity 导入内容并初始化存储。在模块顶层调用 store():
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Blockstudio 会将 script.js 作为 ES 模块加载,并自动生成用于解析 @wordpress/interactivity 的导入映射。
只有当区块定义了自定义操作或回调时,才需要 script.js。仅使用带有 data-wp-context 的声明式指令(如 data-wp-bind--hidden 或 data-wp-text)的区块无需使用任何 JavaScript。
服务器端状态
你可以在模板中使用 wp_interactivity_state(),从 PHP 初始化状态:
<?php
wp_interactivity_state( 'myBlock', array(
'message' => 'Hello from the server',
'count' => get_comments_number(),
) );
?>
<div useBlockProps
data-wp-interactive="myBlock">
<p data-wp-text="state.message">loading...</p>
<p data-wp-text="state.count">0</p>
</div>
服务器端状态仅在前端可用。WordPress 会将状态序列化到页面输出中的 JSON 脚本标签里,交互性 API 会在水合期间读取它。在编辑器中,区块通过 REST API 渲染,因此响应中不包含状态数据。对于需要同时在编辑器和前端生效的状态,请使用 data-wp-context。
回调与操作
操作由用户交互触发(如 data-wp-on--click)。状态或上下文变化时,会使用 data-wp-watch 指令响应式地触发回调。在回调中,你可以调用 getElement() 来访问底层 DOM 元素:
import { store, getContext, getElement } from '@wordpress/interactivity';
store('myBlock', {
callbacks: {
updateWidth: () => {
const { ref } = getElement();
const { isOpen } = getContext();
ref.style.width = isOpen ? '100%' : '0';
},
},
});
编辑器支持
交互性 API 会在区块编辑器 iframe 中加载,因此交互式指令在编辑器预览中也能生效。这包括 data-wp-context、data-wp-bind--*、data-wp-on--*、data-wp-text,以及在 script.js 中定义的自定义存储操作。
提供包含手风琴、标签页、模态框和点赞按钮的完整示例。