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版本及功能存在差异）。
问题出现的场景：站点编辑器、文章编辑器、前端页面，或全部场景。

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
```
、模板、模式及样式变体的内容。