wp-interactivity-api

WP Interactivity API

适用场景

当用户提到以下内容时使用此技能：

• Interactivity API、@wordpress/interactivity，
• data-wp-interactive、data-wp-on--*、data-wp-bind--*、data-wp-context，
• 区块 viewScriptModule / 基于模块的视图脚本，
• 水合问题或“指令不触发”。

所需输入

• 仓库根目录和分诊输出（wp-project-triage）。
• 受影响的区块/主题/插件界面（前端、编辑器或两者）。
• 任何限制：WP 版本、构建中是否支持模块。

流程

1) 检测现有用法和集成方式

搜索：

• data-wp-interactive
• @wordpress/interactivity
• viewScriptModule

判断：

• 这是通过 block.json 视图脚本模块提供交互功能的区块吗？
• 这是主题级交互功能吗？
• 这是插件侧“增强现有标记”的用法吗？

如果要创建新的交互式区块（而不只是调试），优先使用官方脚手架模板：

• @wordpress/create-block-interactive-template（通过 @wordpress/create-block）

2) 确认 store

定位 store 定义并确认：

• 状态结构，
• 操作（修改状态），
• data-wp-on--* 使用的回调/事件处理程序。

3) 服务端渲染（最佳实践）

在服务器上预渲染 HTML，以确保：

• JavaScript 加载前，HTML 中就包含正确的初始状态（避免布局偏移）。
• 获得 SEO 优势，并缩短感知加载时间。
• 客户端 JavaScript 接管时实现无缝水合。

启用服务端指令处理

对于使用 block.json 的组件，添加 supports.interactivity：

{
  "supports": {
    "interactivity": true
  }
}

对于不使用 block.json 的主题/插件，使用 wp_interactivity_process_directives() 处理指令。

在 PHP 中初始化状态/上下文

使用 wp_interactivity_state() 定义初始全局状态：

wp_interactivity_state( 'myPlugin', array(
  'items'    => array( 'Apple', 'Banana', 'Cherry' ),
  'hasItems' => true,
));

对于本地上下文，使用 wp_interactivity_data_wp_context()：

<?php
$context = array( 'isOpen' => false );
?>
<div <?php echo wp_interactivity_data_wp_context( $context ); ?>>
  ...
</div>

在 PHP 中定义派生状态

如果派生状态会影响初始 HTML 渲染，请在 PHP 中复现相关逻辑：

wp_interactivity_state( 'myPlugin', array(
  'items'    => array( 'Apple', 'Banana' ),
  'hasItems' => function() {
    $state = wp_interactivity_state();
    return count( $state['items'] ) > 0;
  }
));

这样可以确保 data-wp-bind--hidden="!state.hasItems" 之类的指令在首次加载时正确渲染。

详细示例和模式请参阅 references/server-side-rendering.md。

4) 安全地实现或修改指令

修改标记指令时：

• 尽量减少指令的使用，并限定其作用范围，
• 优先使用能清晰映射到 store 状态的稳定数据属性，
• 确保服务端渲染的标记与客户端水合保持一致。

WordPress 6.9 的变更：

• data-wp-ignore 已弃用，并将在未来版本中移除。它会破坏上下文继承，并导致客户端导航出现问题。请避免使用。
• 唯一指令 ID：现在可以在同一元素上使用 --- 分隔符来添加多个相同类型的指令（例如，data-wp-on--click---plugin-a="..." 和 data-wp-on--click---plugin-b="..."）。
• 新的 TypeScript 类型：AsyncAction<ReturnType> 和 TypeYield<T> 有助于异步操作的类型标注。

指令速查请参阅 references/directives-quickref.md。

5) 对齐构建/工具链

验证仓库是否支持所需的模块构建方式：

• 如果使用 @wordpress/scripts，优先遵循其惯例。
• 如果使用自定义打包，确认支持模块输出。

6) 调试常见故障

如果交互“没有任何反应”：

• 确认 viewScriptModule 已加入队列/加载，
• 确认 DOM 元素包含 data-wp-interactive，
• 确认 store 命名空间与指令的值一致，
• 确认水合前没有 JavaScript 错误。

请参阅 references/debugging.md。

验证

• 修改后（如适用），wp-project-triage 显示 signals.usesInteractivityApi: true。
• 手动冒烟测试：指令能按预期触发，状态也能按预期更新。
• 如果存在测试：为相关交互流程添加/扩展 Playwright E2E 测试。

故障模式／调试

• 存在指令但未生效：
  • 视图脚本未加载、模块入口点错误，或缺少 data-wp-interactive。
• 水合不匹配／闪烁：
  • 服务端标记与客户端预期不同；简化或对齐初始状态。
  • 未在 PHP 中定义派生状态：使用带闭包的 wp_interactivity_state()。
• 初始内容缺失或错误：
  • 未在 block.json 中设置 supports.interactivity（适用于区块）。
  • 未调用 wp_interactivity_process_directives()（适用于主题／插件）。
  • 渲染前未在 PHP 中初始化状态／上下文。
• 加载时布局偏移：
  • 服务端缺少 state.hasItems 等派生状态，导致缺少 hidden 属性。
• 性能回退：
  • 交互根范围过大；将交互范围限定到更小的子树。
• 客户端导航问题（WordPress 6.9）：
  • getServerState() 和 getServerContext() 现在会在页面转换之间重置，确保代码不会假定过期值仍会保留。
  • 路由器区域现在支持使用 attachTo 动态渲染覆盖层（模态框、弹出窗口）。

升级处理

• 如果仓库构建限制不明确，请询问：“这是使用 @wordpress/scripts，还是自定义打包工具（webpack/vite）？”
• 参考：
  • references/server-side-rendering.md
  • references/directives-quickref.md
  • references/debugging.md