title: “WP 交互 API”
original_url: “https://skills.sh/automattic/agent-skills/wp-interactivity-api”
translation_date: “2026-01-31”
translation_by: “Page Translator Skill”

WP 交互 API

何时使用

当用户提及以下内容时使用此技能：
– 交互 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) 识别存储
找到存储定义并确认：
– 状态形状
– 动作（变更）
– 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) 安全实现或更改指令
处理标记指令时：
– 保持指令使用最小化和作用域限定
– 优先使用与存储状态明确映射的稳定数据属性
– 确保服务器渲染的标记 + 客户端水合对齐

WordPress 6.9 变更：
– data-wp-ignore 已弃用，将在未来版本中移除。它破坏了上下文继承并导致客户端导航问题。避免使用它。
– 唯一指令 ID：现在可以在一个元素上使用 — 分隔符存在多个相同类型的指令（例如，data-wp-on–click—plugin-a=”…” 和 data-wp-on–click—plugin-b=”…”）。
– 新的 TypeScript 类型：AsyncAction 和 TypeYield 有助于异步操作类型化。

有关快速指令提醒，请参阅 references/directives-quickref.md。

5) 构建/工具对齐
验证仓库是否支持所需的模块构建路径：
– 如果使用 @wordpress/scripts，请优先使用其约定。
– 如果使用自定义捆绑，请确认支持模块输出。

6) 调试常见故障模式
如果交互时”无任何反应”：
– 确认 viewScriptModule 已入队/加载
– 确认 DOM 元素具有 data-wp-interactive
– 确认存储命名空间与指令的值匹配
– 确认水合前没有 JS 错误

请参阅 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 进行渲染

博客

WP Interactivity API-WordPress 交互 API 相关技能，用于处理交互性指令和服务器端渲染

WP 交互 API

何时使用

所需输入

步骤

验证

故障模式 / 调试