name: wp-interactivity-api description: “用于构建或调试WordPress交互性API功能（data-wp-*指令、@wordpress/interactivity存储/状态/操作、块viewScriptModule集成），包括性能、水合作用和指令行为。” compatibility: “目标WordPress 6.9+（PHP 7.2.24+）。基于文件系统的代理，使用bash + node。某些工作流需要WP-CLI。”
WordPress交互性API
何时使用
当用户提到以下内容时使用此技能：
- 交互性API，
@wordpress/interactivity， data-wp-interactive，data-wp-on--*，data-wp-bind--*，data-wp-context，- 块
viewScriptModule/ 基于模块的视图脚本， - 水合问题或“指令不触发”。
所需输入
- 仓库根目录 + 问题排查输出（
wp-project-triage）。 - 哪个块/主题/插件表面受影响（前端、编辑器、两者）。
- 任何约束条件：WordPress版本、构建中是否支持模块。
流程
1) 检测现有用法 + 集成风格
搜索：
data-wp-interactive@wordpress/interactivityviewScriptModule
判断：
- 这是否是通过
block.json视图脚本模块提供交互性的块？ - 这是主题级别的交互性吗？
- 这是插件端“增强现有标记”的用法吗？
如果您正在创建一个新的交互式块（不仅仅是调试），请优先使用官方脚手架模板：
@wordpress/create-block-interactive-template（通过@wordpress/create-block）
2) 识别存储
定位存储定义并确认：
- 状态结构，
- 操作（变更），
data-wp-on--*使用的回调/事件处理程序。
3) 安全地实现或更改指令
处理标记指令时：
- 保持指令使用最小化和范围化，
- 优先使用映射到存储状态的稳定数据属性，
- 确保服务器渲染的标记 + 客户端水合作用一致。
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。
4) 构建/工具链对齐
验证仓库是否支持所需的模块构建路径：
- 如果使用
@wordpress/scripts，请遵循其约定。 - 如果使用自定义捆绑，请确认支持模块输出。
5) 调试常见故障模式
如果交互时“没有任何反应”：
- 确认
viewScriptModule已入队/加载， - 确认DOM元素具有
data-wp-interactive， - 确认存储命名空间与指令的值匹配，
- 确认在水合作用之前没有JS错误。
请参阅references/debugging.md。
验证
- 更改后，
wp-project-triage指示signals.usesInteractivityApi: true（如果适用）。 - 手动冒烟测试：指令按预期触发且状态更新。
- 如果存在测试：围绕交互路径添加/扩展Playwright E2E测试。
故障模式 / 调试
- 指令存在但无响应：
- 视图脚本未加载、模块入口点错误或缺少
data-wp-interactive。
- 视图脚本未加载、模块入口点错误或缺少
- 水合作用不匹配 / 闪烁：
- 服务器标记与客户端期望不同；简化或对齐初始状态。
- 性能回归：
- 交互根范围过大；将交互性限定在较小的子树中。
- 客户端导航问题（WordPress 6.9）：
getServerState()和getServerContext()现在在页面转换之间重置——确保您的代码不假定过时的值会持续存在。- 路由器区域现在支持
attachTo以动态渲染覆盖层（模态框、弹出窗口）。
升级
- 如果仓库构建约束不明确，请询问：“这是使用
@wordpress/scripts还是自定义捆绑器（webpack/vite）？” - 参考：
references/directives-quickref.mdreferences/debugging.md