跳转到正文

构建交互组件

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的对象:

JavaScript
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。

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 监听器触发,因为隐藏元素上的指令会暂停。

带服务器状态的点赞按钮

此示例将服务器端状态与客户端操作结合起来。点赞数使用 wp_interactivity_state()从 PHP初始化,点击按钮时会更新。

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中,并可在指令和 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进行调试。 添加监视回调,在开发期间记录上下文变化:

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和其他区块资源。
  • WordPress Interactivity API文档:完整的 API参考,包括本指南未涵盖的 data-wp-each、data-wp-init、data-wp-run和其他指令。