wp-interactivity-api

用途

WP Interactivity API 技能用于构建或调试 WordPress Interactivity API 相关功能。当用户提到 Interactivity API、@wordpress/interactivity、data-wp-* 指令（如 data-wp-interactive、data-wp-on--、data-wp-bind--、data-wp-context）、区块 viewScriptModule 或模块化视图脚本、水合问题或“指令不触发”等情况时可以使用。

所需输入

仓库根目录 + 项目类型（插件、主题或区块）
受影响的界面（前端、编辑器或两者）
WordPress 版本约束

主要能力与使用方式

在区块中设置交互

block.json 中声明 viewScriptModule 并开启 interactivity 支持：

{
  "name": "my-plugin/interactive-block",
  "title": "Interactive Block",
  "viewScriptModule": "file:./view.js",
  "supports": {
    "interactivity": true
  }
}

view.js 以 ES 模块导入 store 和 getContext，定义状态与动作：

import { store, getContext } from '@wordpress/interactivity';

store('my-plugin', {
  state: {
    get isOpen() {
      return getContext().isOpen;
    }
  },
  actions: {
    toggle() {
      const context = getContext();
      context.isOpen = !context.isOpen;
    }
  }
});

核心指令参考

指令	用途	示例
data-wp-interactive	在元素上激活交互	data-wp-interactive="my-plugin"
data-wp-context	提供局部状态	data-wp-context='{"isOpen": false}'
data-wp-bind--attr	将属性绑定到状态	data-wp-bind--aria-expanded="state.isOpen"
data-wp-on--event	处理事件	data-wp-on--click="actions.toggle"
data-wp-class--name	切换 CSS 类	data-wp-class--is-open="state.isOpen"
data-wp-text	设置文本内容	data-wp-text="state.count"
data-wp-watch	运行副作用	data-wp-watch="callbacks.logChanges"

在 PHP 中渲染指令

<?php
$context = array( 'isOpen' => false );
?>
<div
  <?php echo get_block_wrapper_attributes(); ?>
  data-wp-interactive="my-plugin"
  <?php echo wp_interactivity_data_wp_context( $context ); ?>
>
  <button data-wp-on--click="actions.toggle">
    Toggle
  </button>
  <div data-wp-bind--hidden="!state.isOpen">
    Content here
  </div>
</div>

WordPress 6.9 变化

已弃用：

data-wp-ignore 已弃用，避免使用

新功能：

使用 --- 分隔符的唯一指令 ID：

data-wp-on--click---plugin-a="actions.handleA"
data-wp-on--click---plugin-b="actions.handleB"

新增 TypeScript 类型：AsyncAction<ReturnType>、TypeYield<T>
getServerState() 和 getServerContext() 在页面切换之间重置

从零创建交互区块

npx @wordpress/create-block@latest my-interactive-block --template @wordpress/create-block-interactive-template

脚手架会生成：

带 viewScriptModule 的 block.json
带 store 设置的 view.js
带指令的 render.php

验证

手动冒烟测试：指令触发且状态按预期更新
视图脚本在浏览器 Network 标签中加载
水合前无 JS 控制台错误
如存在测试：添加或扩展 Playwright E2E

失败模式与调试

指令不触发：

视图脚本未加载——检查 viewScriptModule 路径
父元素缺少 data-wp-interactive
store 命名空间不匹配
水合前存在 JS 错误

水合不匹配或闪烁：

服务端标记与客户端预期不一致
简化或对齐初始状态

性能问题：

交互根范围过大
将交互限定到更小的子树

调试检查清单：

# 检查视图脚本是否注册
wp eval 'print_r(wp_scripts()->registered);' | grep "view"

# 检查交互使用情况
grep -r "data-wp-interactive" .
grep -r "@wordpress/interactivity" .

升级处理

如果构建约束不明确，询问：

“这是使用 @wordpress/scripts 还是自定义打包器（webpack/vite）？”

可参考 Interactivity API Reference 与 Interactivity API Docs。