wp-block-development

WP Block 开发 (WP Block Development)

适用场景

在进行以下区块相关开发时使用本 Skill：

• 创建新区块，或更新现有区块
• 修改 block.json（脚本/样式/supports/attributes/render/viewScriptModule）
• 排查与修复“区块无效（block invalid）/ 无法保存 / 属性未持久化（attributes not persisting）”问题
• 添加动态渲染（render.php / render_callback）
• 处理区块版本废弃与迁移（deprecated 版本控制）
• 使用区块构建工具链（@wordpress/scripts、@wordpress/create-block、wp-env）

前置输入

• 仓库根目录与目标类型（插件 vs 主题 vs 完整站点）。
• 区块名称/命名空间及其所在位置（若已知，提供 block.json 的路径）。
• 目标 WordPress 版本范围（尤其是使用 Module 或 viewScriptModule 时）。

操作流程

0) 项目排查与区块定位

1. 运行排查脚本：
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. 列出所有区块（确定性扫描）：
   • node skills/wp-block-development/scripts/list_blocks.mjs
3. 明确你需要修改的区块根目录（即包含 block.json 的目录）。

如果当前仓库是一个完整站点（存在 wp-content/ 目录），请明确指定该区块属于哪一个插件或主题。

1) 创建新区块（如需要）

如果需要创建新区块，优先使用脚手架工具生成结构，避免手写模板：

• 使用 @wordpress/create-block 脚手架生成标准的现代区块/插件结构。
• 如果从一开始就需要使用 Interactivity API，请使用 interactive 模板。

参考文档：

• references/creating-new-blocks.md

完成脚手架生成后：

1. 重新运行区块列表脚本，确认新区块的根目录。
2. 按照后续步骤继续操作（选择区块模型、配置元数据、注册、序列化）。

2) 确保 apiVersion 为 3（WordPress 6.9+）

WordPress 6.9 开始在 block.json schema 中强制要求 apiVersion: 3。若区块的 apiVersion 为 2 或更低，在开启 SCRIPT_DEBUG 时会触发控制台警告。

为什么这很重要：

• WordPress 7.0 无论区块 apiVersion 为何，都会在 iframe 中运行文章编辑器。
• apiVersion 3 可确保你的区块在 iframe 编辑器内部正常工作（样式隔离、视口单位、媒体查询等）。

迁移指南： 从版本 2 升级到 3 通常只需更新 block.json 中的 apiVersion 字段即可。不过仍需注意：

• 在开启了 iframe 编辑器的本地环境中进行测试。
• 确保所有的样式 Handle（style handles）都已包含在 block.json 中（未包含在 iframe 中的样式将无法生效）。
• 挂载到特定 window 对象上的第三方脚本可能会遇到作用域/上下文问题。

参考文档：

• references/block-json.md（apiVersion 和 schema 详细说明）

3) 选择合适的区块模型

• 静态区块（Markup 标记直接保存到文章内容中）：实现 save() 方法；保持属性序列化逻辑的稳定。
• 动态区块（服务端渲染）：在 block.json 中配置 render（或在 PHP 中使用 render_callback），保持 save() 极简或返回 null。
• 前端交互行为：
  • 在支持的环境下，优先选择现代基于 Module 的视图脚本 viewScriptModule。
  • 如果主要使用 data-wp-* 指令或 Store，应同时配合使用 wp-interactivity-api。

4) 安全地更新 block.json

在区块的 block.json 中进行修改，然后确认注册信息与元数据保持一致。

按字段查看详细指南，请阅读：

• references/block-json.md

常见坑点：

• 修改 name 会破坏兼容性（应将其视为稳定不变的 API）
• 修改已保存的 Markup 结构但未添加 deprecated 记录，会导致“区块无效（Invalid block）”报错
• 添加了属性但未正确定义 source/serialization（数据源/序列化方式），会导致“属性保存失败”

5) 注册区块（首选服务端注册）

优先使用 PHP 基于元数据（metadata）进行区块注册，尤其是当你需要：

• 动态渲染
• 多语言翻译（wp_set_script_translations）
• 按需/条件加载资源

阅读并应用：

• references/registration.md

6) 实现 edit / save / render 模式

遵循 Wrapper 属性（外层包装属性）的最佳实践：

• 编辑器端：useBlockProps()
• 静态保存端：useBlockProps.save()
• 动态渲染端 (PHP)：get_block_wrapper_attributes()

参考文档：

• references/supports-and-wrappers.md
• references/dynamic-rendering.md（动态区块场景）

7) 嵌套区块 / 内嵌区块（Inner Blocks）

如果你的区块是一个用来嵌套其他区块的“容器”，请将 Inner Blocks 视为一等公民功能：

• 使用 useInnerBlocksProps() 将内嵌区块属性与 Wrapper 属性进行整合。
• 如果修改了内嵌结构 Markup，请时刻注意向下兼容与迁移。

参考文档：

• references/inner-blocks.md

8) 属性与序列化

在修改属性之前：

• 确认属性值的存储位置（注释分隔符 vs HTML vs context 上下文）
• 避免使用已废弃的 meta 属性源（attribute source）

参考文档：

• references/attributes-and-serialization.md

9) 版本迁移与废弃处理（避免“区块无效”报错）

如果你修改了已保存的 Markup 结构或属性：

1. 添加一条 deprecated 配置项（按“最新 → 最旧”顺序排列）。
2. 为旧版本提供对应的 save 函数，并可选择性提供 migrate 函数来规范化属性。

参考文档：

• references/deprecations.md

10) 构建工具与验证命令

优先使用仓库中已有/现成的工具链：

• @wordpress/scripts（常见）→ 运行现有的 npm 脚本
• wp-env（常见）→ 用于本地 WP 环境搭建与端到端测试 (E2E)

参考文档：

• references/tooling-and-testing.md

验证检查

• 区块成功显示在插入器（Inserter）中，并能顺利插入文章。
• 保存文章并刷新页面后，不会出现“区块无效（Invalid block）”错误。
• 前端渲染输出符合预期（静态区块：显示保存的 Markup；动态区块：显示服务端渲染结果）。
• 静态/动态资源在预期的位置正常加载（编辑器端 vs 前端）。
• 运行排查步骤中推荐的仓库 Lint / Build / Test 命令。

常见故障 / 调试排查

遇到问题时，先从这里开始排查：

• references/debugging.md（常见故障 + 最快排查方法）
• references/attributes-and-serialization.md（属性无法保存）
• references/deprecations.md（修改后提示区块无效）

进阶求助 / 查阅官方文档

如果不确定 WordPress 上游行为或版本兼容性，请先查阅官方权威文档：

• WordPress 开发者资源中心（Block Editor Handbook, Theme Handbook, Plugin Handbook）
• Gutenberg 官方仓库文档（获取最新的前沿特性行为）