跳转到正文

交互性

Blockstudio 支持 WordPress 交互性 API,为区块添加响应式客户端行为提供了标准方式。在 block.json 中设置 interactivity,然后由 Blockstudio 负责在前端和编辑器中加载 API。

配置

通过将 API 添加到 block.json 中的 blockstudio 键,即可启用交互性 interactivity:

JSON
{
  "name": "my-theme/interactive-block",
  "title": "Interactive Block",
  "category": "text",
  "icon": "star-filled",
  "description": "A block with interactive behavior.",
  "blockstudio": {
    "interactivity": true
  }
}

你也可以使用对象形式:

JSON
{
  "blockstudio": {
    "interactivity": {
      "enqueue": true
    }
  }
}

两种形式等效。

模板

在区块模板中添加交互性 API 指令。data-wp-interactive 属性定义存储命名空间,其他 data-wp-* 属性则控制响应式行为。

PHP
<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():

JavaScript
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
<?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 元素:

JavaScript
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 中定义的自定义存储操作。

构建交互式组件

提供包含手风琴、标签页、模态框和点赞按钮的完整示例。