在构建或调试 WordPress Interactivity API 功能（包括 data-wp-* 指令、@wordpress/interactivity store/state/actions、区块 viewScriptModule 集成以及 wp_interactivity_*() 函数）时使用，涵盖性能优化、水合 (hydration) 和指令行为调试。
WP Interactivity API
使用场景
当用户提到以下内容时使用此 Skill：
- Interactivity API、
@wordpress/interactivity data-wp-interactive、data-wp-on--*、data-wp-bind--*、data-wp-context- 区块
viewScriptModule/ 基于模块的视图脚本 - 水合 (hydration) 问题或“指令未生效/未触发”
所需输入
- 项目根目录 + 判别排查输出（
wp-project-triage）。 - 受影响的区块/主题/插件位置（前端、编辑器或两者兼有）。
- 任何约束条件：WP 版本、构建流程中是否支持模块。
操作步骤
1) 检测现有用法与集成方式
搜索以下关键字：
data-wp-interactive@wordpress/interactivityviewScriptModule
判断并明确：
- 这是通过
block.json中的 view script module 提供交互功能的区块吗？ - 这是主题层面的交互吗？
- 这是插件侧“增强现有标记 (markup)”的用法吗？
如果是在创建全新的交互式区块（而不仅仅是调试），优先使用官方脚手架模板：
@wordpress/create-block-interactive-template（通过@wordpress/create-block运行）
2) 确定 Store
定位 Store 定义并确认：
- state 的数据结构 (state shape)
- actions（状态变更/mutations）
data-wp-on--*所调用的 callbacks / 事件处理函数
3) 服务端渲染（最佳实践）
在输出 HTML 前先在服务端完成预渲染，以确保：
- JavaScript 加载前 HTML 即具备正确的初始状态（避免页面布局偏移）。
- 提升 SEO 表现及感知加载速度。
- 客户端 JavaScript 接管时能够无缝水合 (hydration)。
开启服务端指令处理
对于使用 block.json 的组件，添加 supports.interactivity：
{
"supports": {
"interactivity": true
}
}
对于未使用 block.json 的主题/插件，使用 wp_interactivity_process_directives() 来处理指令。
在 PHP 中初始化 state/context
使用 wp_interactivity_state() 定义全局初始状态：
wp_interactivity_state( 'myPlugin', array(
'items' => array( 'Apple', 'Banana', 'Cherry' ),
'hasItems' => true,
));
对于局部 context，使用 wp_interactivity_data_wp_context()：
<?php
$context = array( 'isOpen' => false );
?>
<div <?php echo wp_interactivity_data_wp_context( $context ); ?>>
...
</div>
在 PHP 中定义派生状态 (Derived State)
当派生状态影响初始 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) 安全地实现或修改指令
修改 markup 指令时：
- 保持指令使用尽量轻量且作用域受控
- 优先使用能清晰映射到 store state 的稳定数据属性
- 确保服务端渲染的 markup 与客户端水合保持一致
WordPress 6.9 变更说明：
data-wp-ignore已弃用，并将在未来版本中移除。它会破坏 context 的继承机制并引发客户端导航问题，请避免使用。- 指令 ID 唯一化：现在可以使用
---分隔符在单个元素上使用多个同类型指令（例如data-wp-on--click---plugin-a="..."和data-wp-on--click---plugin-b="..."）。 - 全新 TypeScript 类型：
AsyncAction<ReturnType>和TypeYield<T>可用于协助异步 action 的类型定义。
指令快速速查请参考 references/directives-quickref.md。
5) 构建/工具链对齐
确认代码库支持所需的 module 构建路径：
- 如果使用了
@wordpress/scripts，优先遵循其规范。 - 如果使用了自定义打包工具，请确认支持 module 格式输出。
6) 排查常见故障模式
如果交互时“毫无反应”：
- 确认
viewScriptModule已正确入队 (enqueued) 并加载； - 确认 DOM 元素包含
data-wp-interactive； - 确认 Store 的命名空间与指令的值相匹配；
- 确认水合发生前没有出现 JS 报错。
详见 references/debugging.md。
验证
- 修改后（如适用），
wp-project-triage应显示signals.usesInteractivityApi: true。 - 手动冒烟测试：指令按预期触发且状态正常更新。
- 如果存在测试：针对交互路径新增或扩充 Playwright E2E 测试。
常见故障模式 / 调试指南
- 指令存在但未生效：
- view script 未加载、模块入口点配置错误或缺少
data-wp-interactive。
- view script 未加载、模块入口点配置错误或缺少
- 水合不匹配 / 页面闪烁 (Hydration mismatch / flicker)：
- 服务端 markup 与客户端预期不一致；请简化或对齐初始状态。
- 未在 PHP 中定义派生状态：请使用带有闭包 (closure) 的
wp_interactivity_state()。
- 初始内容缺失或错误：
- （对于区块）未在
block.json中设置supports.interactivity。 - （对于主题/插件）未调用
wp_interactivity_process_directives()。 - 渲染前未在 PHP 中初始化 state/context。
- （对于区块）未在
- 加载时发生布局偏移 (Layout shift)：
- 服务端缺少像
state.hasItems这样的派生状态，导致缺少hidden属性。
- 服务端缺少像
- 性能下降：
- 交互根节点 (interactive root) 作用域过大；应将交互范围缩小至更小的子树。
- 客户端导航问题（WordPress 6.9）：
getServerState()和getServerContext()现在会在页面切换间重置——请确保代码不会假定旧值仍然保留。- 路由区域 (Router regions) 现在支持
attachTo，用于动态渲染覆盖层（如模态框、弹窗）。
问题升级 / 排查求助
- 如果代码库构建约束不明确，可询问："请问项目是在使用
@wordpress/scripts还是自定义打包工具 (webpack/vite)？" - 参考文档：
references/server-side-rendering.mdreferences/directives-quickref.mdreferences/debugging.md
