wp-block-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WP Block Development

WordPress区块开发

When to use

适用场景

Use this skill for block work such as:

creating a new block, or updating an existing one
changing
```
block.json
```
(scripts/styles/supports/attributes/render/viewScriptModule)
fixing “block invalid / not saving / attributes not persisting”
adding dynamic rendering (
```
render.php
```
/
```
render_callback
```
)
block deprecations and migrations (
```
deprecated
```
versions)

build tooling for blocks (

@wordpress/scripts

@wordpress/create-block

wp-env

)

本技能适用于以下区块开发工作：

创建新区块或更新现有区块
修改
```
block.json
```
（脚本/样式/supports/属性/渲染/viewScriptModule）
修复“区块无效/无法保存/属性不持久”问题
添加动态渲染（
```
render.php
```
/
```
render_callback
```
）
区块弃用与迁移（
```
deprecated
```
版本）

区块构建工具（

@wordpress/scripts

、

@wordpress/create-block

、

wp-env

）

Inputs required

所需输入

Repo root and target (plugin vs theme vs full site).
The block name/namespace and where it lives (path to
```
block.json
```
if known).
Target WordPress version range (especially if using modules /
```
viewScriptModule
```
).

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

Procedure

操作流程

0) Triage and locate blocks

0) 分类排查与区块定位

Run triage:

node skills/wp-project-triage/scripts/detect_wp_project.mjs

List blocks (deterministic scan):

node skills/wp-block-development/scripts/list_blocks.mjs

Identify the block root (directory containing
```
block.json
```
) you’re changing.

If this repo is a full site (

wp-content/

present), be explicit about which plugin/theme contains the block.

运行分类排查脚本：

node skills/wp-project-triage/scripts/detect_wp_project.mjs

列出所有区块（确定性扫描）：

node skills/wp-block-development/scripts/list_blocks.mjs

确定你要修改的区块根目录（包含
```
block.json
```
的目录）。

如果仓库是完整站点（存在

wp-content/

），请明确说明该区块属于哪个插件/主题。

1) Create a new block (if needed)

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

If you are creating a new block, prefer scaffolding rather than hand-rolling structure:

Use
```
@wordpress/create-block
```
to scaffold a modern block/plugin setup.
If you need Interactivity API from day 1, use the interactive template.

Read:

```
references/creating-new-blocks.md
```

After scaffolding:

Re-run the block list script and confirm the new block root.
Continue with the remaining steps (model choice, metadata, registration, serialization).

若要创建新区块，优先使用脚手架而非手动构建结构：

使用
```
@wordpress/create-block
```
搭建现代化的区块/插件架构。
如果从一开始就需要Interactivity API，请使用交互式模板。

参考文档：

```
references/creating-new-blocks.md
```

脚手架搭建完成后：

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

2) Ensure apiVersion 3 (WordPress 6.9+)

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

WordPress 6.9 enforces

apiVersion: 3

in the block.json schema. Blocks with apiVersion 2 or lower trigger console warnings when

SCRIPT_DEBUG

is enabled.

Why this matters:

WordPress 7.0 will run the post editor in an iframe regardless of block apiVersion.
apiVersion 3 ensures your block works correctly inside the iframed editor (style isolation, viewport units, media queries).

Migration: Changing from version 2 to 3 is usually as simple as updating the

apiVersion

field in

block.json

. However:

Test in a local environment with the iframe editor enabled.
Ensure any style handles are included in
```
block.json
```
(styles missing from the iframe won't apply).
Third-party scripts attached to a specific
```
window
```
may have scoping issues.

Read:

```
references/block-json.md
```
(apiVersion and schema details)

WordPress 6.9强制要求

block.json

schema中使用

apiVersion: 3

。当启用

SCRIPT_DEBUG

时，使用apiVersion 2或更低版本的区块会触发控制台警告。

重要性说明：

WordPress 7.0将在iframe中运行文章编辑器，无论区块使用哪个apiVersion。
apiVersion 3确保你的区块在iframe编辑器中正常工作（样式隔离、视窗单位、媒体查询）。

迁移步骤： 从版本2升级到3通常只需更新

block.json

中的

apiVersion

字段。但需注意：

在启用iframe编辑器的本地环境中进行测试。
确保所有样式句柄都已包含在
```
block.json
```
中（iframe中缺失的样式将无法生效）。
附加到特定
```
window
```
的第三方脚本可能会出现作用域问题。

参考文档：

```
references/block-json.md
```
（apiVersion及schema详情）

3) Pick the right block model

3) 选择合适的区块模型

Static block (markup saved into post content): implement
```
save()
```
; keep attributes serialization stable.
Dynamic block (server-rendered): use
```
render
```
in
```
block.json
```
(or
```
render_callback
```
in PHP) and keep
```
save()
```
minimal or
```
null
```
.
Interactive frontend behavior:
- Prefer
```
viewScriptModule
```
  for modern module-based view scripts where supported.
- If you're working primarily on
```
data-wp-*
```
  directives or stores, also use
```
wp-interactivity-api
```
  .

静态区块（标记保存到文章内容中）：实现
```
save()
```
函数；保持属性序列化稳定。
动态区块（服务器端渲染）：在
```
block.json
```
中使用
```
render
```
（或在PHP中使用
```
render_callback
```
），并将
```
save()
```
设为极简或
```
null
```
。
交互式前端行为：
- 优先在支持的环境中使用
```
viewScriptModule
```
  作为基于模块的现代视图脚本。
- 若主要处理
```
data-wp-*
```
  指令或存储，同时使用
```
wp-interactivity-api
```
  。

4) Update

block.json

safely

4) 安全更新

block.json

Make changes in the block’s

block.json

, then confirm registration matches metadata.

For field-by-field guidance, read:

```
references/block-json.md
```

Common pitfalls:

changing
```
name
```
breaks compatibility (treat it as stable API)
changing saved markup without adding
```
deprecated
```
causes “Invalid block”
adding attributes without defining source/serialization correctly causes “attribute not saving”

在区块的

block.json

中进行修改，然后确认注册信息与元数据匹配。

如需逐字段指导，请参考：

```
references/block-json.md
```

常见陷阱：

修改
```
name
```
会破坏兼容性（将其视为稳定API）
修改已保存的标记但未添加
```
deprecated
```
会导致“区块无效”
添加属性但未正确定义source/序列化规则会导致“属性无法保存”

5) Register the block (server-side preferred)

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

Prefer PHP registration using metadata, especially when:

you need dynamic rendering
you need translations (
```
wp_set_script_translations
```
)
you need conditional asset loading

Read and apply:

```
references/registration.md
```

优先使用PHP基于元数据注册区块，尤其是在以下场景：

需要动态渲染
需要翻译支持（
```
wp_set_script_translations
```
）
需要条件性加载资源

参考并应用：

```
references/registration.md
```

6) Implement edit/save/render patterns

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

Follow wrapper attribute best practices:

Editor:
```
useBlockProps()
```
Static save:
```
useBlockProps.save()
```
Dynamic render (PHP):
```
get_block_wrapper_attributes()
```

Read:

```
references/supports-and-wrappers.md
```
```
references/dynamic-rendering.md
```
(if dynamic)

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

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

参考文档：

```
references/supports-and-wrappers.md
```
```
references/dynamic-rendering.md
```
（若使用动态渲染）

7) Inner blocks (block composition)

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

If your block is a “container” that nests other blocks, treat Inner Blocks as a first-class feature:

Use
```
useInnerBlocksProps()
```
to integrate inner blocks with wrapper props.
Keep migrations in mind if you change inner markup.

Read:

```
references/inner-blocks.md
```

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

使用
```
useInnerBlocksProps()
```
将内部区块与包装器属性集成。
若修改内部标记，请考虑迁移方案。

参考文档：

```
references/inner-blocks.md
```

8) Attributes and serialization

8) 属性与序列化

Before changing attributes:

confirm where the attribute value lives (comment delimiter vs HTML vs context)
avoid the deprecated
```
meta
```
attribute source

Read:

references/attributes-and-serialization.md

修改属性前：

确认属性值的存储位置（注释分隔符、HTML或上下文）
避免使用已弃用的
```
meta
```
属性源

参考文档：

references/attributes-and-serialization.md

9) Migrations and deprecations (avoid "Invalid block")

9) 迁移与弃用（避免“区块无效”）

If you change saved markup or attributes:

Add a
```
deprecated
```
entry (newest → oldest).
Provide
```
save
```
for old versions and an optional
```
migrate
```
to normalize attributes.

Read:

```
references/deprecations.md
```

若修改已保存的标记或属性：

添加
```
deprecated
```
条目（按从新到旧的顺序）。
为旧版本提供
```
save
```
函数，可选择性添加
```
migrate
```
函数以标准化属性。

参考文档：

```
references/deprecations.md
```

10) Tooling and verification commands

10) 工具与验证命令

Prefer whatever the repo already uses:

```
@wordpress/scripts
```
(common) → run existing npm scripts
```
wp-env
```
(common) → use for local WP + E2E

Read:

```
references/tooling-and-testing.md
```

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

```
@wordpress/scripts
```
（常用）→ 运行现有npm脚本
```
wp-env
```
（常用）→ 用于本地WordPress环境及端到端测试

参考文档：

```
references/tooling-and-testing.md
```

Verification

验证步骤

Block appears in inserter and inserts successfully.
Saving + reloading does not create “Invalid block”.
Frontend output matches expectations (static: saved markup; dynamic: server output).
Assets load where expected (editor vs frontend).
Run the repo’s lint/build/tests that triage recommends.

区块出现在插入器中并能成功插入。
保存并重新加载后不会出现“区块无效”提示。
前端输出符合预期（静态区块：已保存的标记；动态区块：服务器输出）。
资源在预期位置加载（编辑器端 vs 前端）。
运行分类排查推荐的仓库代码检查/构建/测试脚本。

Failure modes / debugging

故障模式与调试

If something fails, start here:

```
references/debugging.md
```
(common failures + fastest checks)

references/attributes-and-serialization.md

(attributes not saving)

```
references/deprecations.md
```
(invalid block after change)

若出现问题，从以下文档开始排查：

```
references/debugging.md
```
（常见故障+快速检查）

references/attributes-and-serialization.md

（属性无法保存）

```
references/deprecations.md
```
（修改后出现区块无效）

Escalation

升级处理

If you’re uncertain about upstream behavior/version support, consult canonical docs first:

WordPress Developer Resources (Block Editor Handbook, Theme Handbook, Plugin Handbook)
Gutenberg repo docs for bleeding-edge behaviors

若对上游行为/版本支持不确定，请先查阅官方文档：

WordPress开发者资源（区块编辑器手册、主题手册、插件手册）
Gutenberg仓库文档（前沿功能）

wp-block-development

Original

Translation

WP Block Development

WordPress区块开发

When to use

适用场景

Inputs required

所需输入

Procedure

操作流程

0) Triage and locate blocks

0) 分类排查与区块定位

1) Create a new block (if needed)

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

2) Ensure apiVersion 3 (WordPress 6.9+)

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

3) Pick the right block model

3) 选择合适的区块模型

4) Update
`block.json`
safely

4) 安全更新
`block.json`

5) Register the block (server-side preferred)

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

6) Implement edit/save/render patterns

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

7) Inner blocks (block composition)

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

8) Attributes and serialization

8) 属性与序列化

9) Migrations and deprecations (avoid "Invalid block")

9) 迁移与弃用（避免“区块无效”）

10) Tooling and verification commands

10) 工具与验证命令

Verification

验证步骤

Failure modes / debugging

故障模式与调试

Escalation

升级处理

wp-block-development

Original

Translation

WP Block Development

WordPress区块开发

When to use

适用场景

Inputs required

所需输入

Procedure

操作流程

0) Triage and locate blocks

0) 分类排查与区块定位

1) Create a new block (if needed)

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

2) Ensure apiVersion 3 (WordPress 6.9+)

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

3) Pick the right block model

3) 选择合适的区块模型

4) Update block.json safely

4) 安全更新block.json

5) Register the block (server-side preferred)

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

6) Implement edit/save/render patterns

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

7) Inner blocks (block composition)

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

8) Attributes and serialization

8) 属性与序列化

9) Migrations and deprecations (avoid "Invalid block")

9) 迁移与弃用（避免“区块无效”）

10) Tooling and verification commands

10) 工具与验证命令

Verification

验证步骤

Failure modes / debugging

故障模式与调试

Escalation

升级处理

4) Update
`block.json`
safely

4) 安全更新
`block.json`