WP Interactivity API 是 WordPress 官方提供的技能，目标是帮助开发者构建或调试基于 WordPress Interactivity API 的交互功能。当用户提到 Interactivity API、@wordpress/interactivity、data-wp-interactive、data-wp-on--、data-wp-bind--、data-wp-context、基于 module 的区块视图脚本（block viewScriptModule），或遇到水合问题、指令不触发等情况时，即可使用本技能。
用途与适用场景 本技能覆盖三类使用面：区块通过 block.json 的视图脚本模块提供交互、主题级别的交互、以及插件侧“增强现有标记”的用法。它同样适用于调试交互无效、水合不匹配、首屏内容缺失或布局抖动等问题。若要创建全新的交互式区块（而非仅调试），建议优先使用官方脚手架模板 @wordpress/create-block-interactive-template（经由 @wordpress/create-block）。
输入前提 使用时需要仓库根目录与分诊输出（wp-project-triage），明确受影响的区块/主题/插件面（前端、编辑器或两者），以及约束条件，例如 WordPress 版本、构建是否支持模块。
主要流程 第一步是检测现有用法与集成方式：搜索 data-wp-interactive、@wordpress/interactivity、viewScriptModule，判断属于哪种交互集成形态。第二步是定位 store：确认 state 结构、actions（变更操作）、以及 data-wp-on--* 使用的事件回调。第三步是服务端渲染最佳实践：在输出前于服务端预渲染 HTML，以保证 JavaScript 加载前初始状态正确、避免布局抖动，并利于 SEO 和更快感知加载，客户端接替时能无缝水合。对使用 block.json 的组件，添加 supports.interactivity；对无 block.json 的主题或插件，使用 wp_interactivity_process_directives() 处理指令。使用 wp_interactivity_state() 定义初始全局状态，用 wp_interactivity_data_wp_context() 定义局部上下文。当派生状态影响初始 HTML 渲染时，需在 PHP 中复刻该逻辑，确保如 data-wp-bind--hidden="!state.hasItems" 这类指令首次加载即正确渲染。
指令实现与 6.9 变更 修改标记指令时应保持指令最小化且有作用域，优先使用能清晰映射到 store 状态的稳定数据属性，并确保服务端渲染标记与客户端水合一致。WordPress 6.9 中 data-wp-ignore 已弃用并将被移除，它会破坏上下文继承并影响客户端导航，应避免使用；同一元素上现可通过 --- 分隔符存在多个同类型指令；新增 TypeScript 类型 AsyncAction<ReturnType> 与 TypeYield<T> 辅助异步 action 类型。
构建工具与调试 需确认仓库支持所需的模块构建路径：若使用 @wordpress/scripts，优先遵循其约定；若为自定义打包，确认支持模块输出。交互“无反应”时，依次确认视图脚本模块是否入队/加载、DOM 元素是否有 data-wp-interactive、store 命名空间是否与指令值匹配、水合前是否有 JS 错误。
验证与常见故障 验证方面：变更后 wp-project-triage 应显示 usesInteractivityApi: true；手动冒烟测试指令触发与状态更新；如有测试，围绕交互路径扩展 Playwright E2E。常见故障包括：指令存在但不生效（脚本未加载、模块入口错误或缺少 data-wp-interactive）；水合不匹配/闪烁（服务端标记与客户端预期不符）；PHP 中未定义派生状态；初始内容缺失或错误（未设置 supports.interactivity 或未调用 wp_interactivity_process_directives()、未在渲染前初始化状态/上下文）；加载时布局抖动（服务端缺少派生状态如 state.hasItems）；性能退化（交互根作用域过宽）；以及 6.9 的客户端导航问题（getServerState() 与 getServerContext() 在页面切换间会重置，路由区域现支持 attachTo 动态渲染模态框与弹窗等覆盖层）。若构建约束不明确，可询问是否使用 @wordpress/scripts 或自定义打包器（webpack/vite），并可参考 server-side-rendering.md、directives-quickref.md、debugging.md 等资料。