wp-block-development

WP 区块开发

适用场景

在进行以下区块工作时使用此技能：

• 创建新区块或更新现有区块
• 修改 block.json（脚本／样式／支持项／属性／渲染／viewScriptModule）
• 修复“区块无效／无法保存／属性未持久化”等问题
• 添加动态渲染（render.php／render_callback）
• 处理区块弃用和迁移（deprecated 版本）
• 配置区块构建工具（@wordpress/scripts、@wordpress/create-block、wp-env）

所需输入

• 仓库根目录和目标（插件、主题还是完整站点）。
• 区块名称／命名空间及其所在位置（如果已知，提供 block.json 的路径）。
• 目标 WordPress 版本范围（尤其是在使用模块／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，请使用交互式模板。

阅读：

• references/creating-new-blocks.md

脚手架搭建完成后：

1. 重新运行区块列表脚本，确认新的区块根目录。
2. 继续完成剩余步骤（模型选择、元数据、注册、序列化）。

2) 确保使用 apiVersion 3（WordPress 6.9+）

WordPress 6.9 会在 block.json 架构中强制要求 apiVersion: 3。启用 SCRIPT_DEBUG 时，apiVersion 为 2 或更低版本的区块会触发控制台警告。

这很重要，因为：

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

迁移： 从版本 2 改为版本 3，通常只需更新 block.json 中的 apiVersion 字段。不过：

• 请在启用了 iframe 编辑器的本地环境中进行测试。
• 确保所有样式句柄都已包含在 block.json 中（未包含的样式无法在 iframe 中应用）。
• 附加到特定 window 的第三方脚本可能存在作用域问题。

阅读：

• references/block-json.md（apiVersion 和架构详情）

3) 选择合适的区块模型

• 静态区块（标记保存在文章内容中）：实现 save()；确保属性序列化保持稳定。
• 动态区块（由服务器渲染）：在 block.json 中使用 render（或在 PHP 中使用 render_callback），并让 save() 保持精简或设为 null。
• 交互式前端行为：
  • 对于受支持的现代模块化视图脚本，优先使用 viewScriptModule。
  • 如果主要处理 data-wp-* 指令或存储，也使用 wp-interactivity-api。

4) 安全更新 block.json

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

字段说明请阅读：

• references/block-json.md

常见问题：

• 修改 name 会破坏兼容性（应将其视为稳定 API）
• 修改已保存的标记却未添加 deprecated，会导致“区块无效”
• 添加属性却未正确设置来源／序列化方式，会导致“属性未保存”

5) 注册区块（优先使用服务器端注册）

优先使用 PHP 根据元数据注册，尤其是在以下情况下：

• 需要动态渲染
• 需要翻译（wp_set_script_translations）
• 需要有条件地加载资源

阅读并遵循：

• references/registration.md

6) 实现编辑／保存／渲染模式

遵循包装器属性最佳实践：

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

阅读：

• references/supports-and-wrappers.md
• references/dynamic-rendering.md（如果是动态渲染）

7) 内部区块（区块组合）

如果你的区块是嵌套其他区块的“容器”，请将内部区块视为一项核心功能：

• 使用 useInnerBlocksProps() 将内部区块与包装器属性集成。
• 更改内部标记时，请考虑迁移。

阅读：

• references/inner-blocks.md

8) 属性与序列化

更改属性之前：

• 确认属性值存放的位置（注释分隔符、HTML 还是上下文）
• 避免使用已弃用的 meta 属性来源

阅读：

• references/attributes-and-serialization.md

9) 迁移与弃用（避免出现“Invalid block”）

如果更改已保存的标记或属性：

1. 添加一个 deprecated 条目（从最新到最旧）。
2. 为旧版本提供 save，并可选择提供 migrate 来规范化属性。

阅读：

• references/deprecations.md

10) 工具与验证命令

优先使用仓库已有的工具：

• @wordpress/scripts（常见）→ 运行现有的 npm 脚本
• wp-env（常见）→ 用于本地 WP 和端到端测试

阅读：

• references/tooling-and-testing.md

验证

• 区块会显示在插入器中，并能成功插入。
• 保存并重新加载后，不会出现“Invalid block”。
• 前端输出符合预期（静态：已保存的标记；动态：服务端输出）。
• 资源会在预期位置加载（编辑器或前端）。
• 运行仓库的 lint、构建和测试，以及分流工具建议的检查。

故障模式／调试

如果遇到问题，请从这里开始：

• references/debugging.md（常见故障与最快检查方法）
• references/attributes-and-serialization.md（属性未保存）
• references/deprecations.md（更改后区块无效）

升级处理

如果不确定上游行为或版本支持情况，请先查阅规范文档：

• WordPress 开发者资源（区块编辑器手册、主题手册、插件手册）
• Gutenberg 仓库文档，了解前沿行为