wp-block-themes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WP Block Themes

WordPress区块主题

When to use

适用场景

Use this skill for block theme work such as:

editing
```
theme.json
```
(presets, settings, styles, per-block styles)
adding or changing templates (
```
templates/*.html
```
) and template parts (
```
parts/*.html
```
)
adding patterns (
```
patterns/*.php
```
) and controlling what appears in the inserter
adding style variations (
```
styles/*.json
```
)
debugging “styles not applying” / “editor doesn’t reflect theme.json”

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

编辑
```
theme.json
```
（预设、设置、样式、区块级样式）
添加或修改模板（
```
templates/*.html
```
）与模板片段（
```
parts/*.html
```
）
添加区块模式（
```
patterns/*.php
```
）并控制插入器中显示的内容
添加样式变体（
```
styles/*.json
```
）
调试“样式未生效”/“编辑器未同步theme.json设置”问题

Inputs required

所需输入

Repo root and which theme is targeted (theme directory if multiple exist).
Target WordPress version range (theme.json version and features vary by core version).
Where the issue manifests: Site Editor, post editor, frontend, or all.

代码库根目录以及目标主题（若存在多个主题，需指定主题目录）
目标WordPress版本范围（theme.json的版本和功能会随WordPress核心版本不同而变化）
问题出现的场景：站点编辑器、文章编辑器、前端页面，或全部场景

Procedure

操作步骤

0) Triage and locate block theme roots

0) 分类排查并定位区块主题根目录

Run triage:

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

Detect theme roots + key folders:

node skills/wp-block-themes/scripts/detect_block_themes.mjs

If multiple themes exist, pick one and scope all changes to that theme root.

执行分类排查：

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

检测主题根目录及关键文件夹：

node skills/wp-block-themes/scripts/detect_block_themes.mjs

若存在多个主题，请选择其中一个，并将所有操作限定在该主题根目录下。

1) Create a new block theme (if needed)

1) 创建新的区块主题（如有需要）

If you are creating a new block theme from scratch (or converting a classic theme):

Prefer starting from a known-good scaffold (or exporting from a WP environment) rather than guessing file layout.
Be explicit about the minimum supported WordPress version because
```
theme.json
```
schema versions differ.

Read:

```
references/creating-new-block-theme.md
```

After creating the theme root, re-run

detect_block_themes

and continue below.

如果要从零开始创建新的区块主题（或从经典主题转换）：

建议从经过验证的脚手架开始（或从WordPress环境导出），而非自行猜测文件结构。
明确最低支持的WordPress版本，因为不同版本的
```
theme.json
```
schema存在差异。

参考文档：

```
references/creating-new-block-theme.md
```

创建主题根目录后，重新运行

detect_block_themes

，然后继续后续步骤。

2) Confirm theme type and override expectations

2) 确认主题类型与样式覆盖规则

Block theme indicators:
- ```
theme.json
```
  present
- ```
templates/
```
  and/or
```
parts/
```
  present
Remember the style hierarchy:
- core defaults → theme.json → child theme → user customizations
- user customizations can make theme.json edits appear “ignored”

Read:

```
references/debugging.md
```
(style hierarchy + fastest checks)

区块主题的标识：
- 存在
```
theme.json
```
  文件
- 存在
```
templates/
```
  和/或
```
parts/
```
  文件夹
牢记样式层级：
- 核心默认值 → theme.json → 子主题 → 用户自定义设置
- 用户自定义设置可能会导致theme.json的修改看似“未生效”

参考文档：

```
references/debugging.md
```
（样式层级+快速排查方法）

3) Make

theme.json

changes safely

3) 安全修改theme.json

Decide whether you are changing:

settings (what the UI allows): presets, typography scale, colors, layout, spacing
styles (how it looks by default): CSS-like rules for elements/blocks

Read:

```
references/theme-json.md
```

明确修改的类型：

设置项（UI允许的操作）：预设值、排版比例、颜色、布局、间距
样式项（默认外观）：针对元素/区块的类CSS规则

参考文档：

```
references/theme-json.md
```

4) Templates and template parts

4) 模板与模板片段

Templates live under
```
templates/
```
and are HTML.
Template parts live under
```
parts/
```
and must not be nested in subdirectories.

Read:

```
references/templates-and-parts.md
```

模板存储在
```
templates/
```
目录下，格式为HTML
模板片段存储在
```
parts/
```
目录下，且不能嵌套在子目录中

参考文档：

```
references/templates-and-parts.md
```

5) Patterns

5) 区块模式

Prefer filesystem patterns under

patterns/

when you want theme-owned patterns.

Read:

```
references/patterns.md
```

若需要主题专属的区块模式，优先使用

patterns/

目录下的文件系统模式。

参考文档：

```
references/patterns.md
```

6) Style variations

6) 样式变体

Style variations are JSON files under

styles/

. Note: once a user picks a style variation, that selection is stored in the DB, so changing the file may not “update what the user sees” automatically.

Read:

```
references/style-variations.md
```

样式变体是

styles/

目录下的JSON文件。注意：一旦用户选择了某个样式变体，该选择会存储在数据库中，因此修改文件后不会自动同步到用户的显示效果。

参考文档：

```
references/style-variations.md
```

Verification

验证

Site Editor reflects changes where expected (Styles UI, templates, patterns).
Frontend renders with expected styles.
If styles aren’t changing, confirm whether user customizations override theme defaults.
Run the repo’s build/lint scripts if assets are involved (fonts, custom JS/CSS build).

站点编辑器中能正确反映预期的修改（样式UI、模板、区块模式）
前端页面渲染出预期的样式
若样式未变化，请确认是否存在用户自定义设置覆盖了主题默认值
若涉及资源文件（字体、自定义JS/CSS构建），请运行代码库的构建/ lint脚本

Failure modes / debugging

故障模式与调试

Start with:

```
references/debugging.md
```

Common issues:

wrong theme root (editing an inactive theme)
user customizations override your defaults
invalid
```
theme.json
```
shape/typos prevent application
templates/parts in wrong folders (or nested parts)

首先参考：

```
references/debugging.md
```

常见问题：

主题根目录错误（编辑了未激活的主题）
用户自定义设置覆盖了默认值
```
theme.json
```
格式错误/拼写错误导致无法生效
模板/片段存放目录错误（或嵌套存放片段）

Escalation

升级处理

If upstream behavior is unclear, consult canonical docs:

Theme Handbook and Block Editor Handbook for
```
theme.json
```
, templates, patterns, and style variations.

若上游行为不明确，请参考官方文档：

主题手册与区块编辑器手册中关于theme.json、模板、区块模式和样式变体的内容。