wp-block-themes

WP 区块主题

适用场景

在进行区块主题相关工作时使用此技能，例如：

• 编辑 theme.json（预设、设置、样式、单区块样式）
• 添加或更改模板（templates/*.html）和模板部件（parts/*.html）
• 添加样板（patterns/*.php）并控制其在插入器中的显示内容
• 添加样式变体（styles/*.json）
• 调试“样式未生效”/“编辑器未反映 theme.json 设置”

所需输入

• 仓库根目录以及目标主题（如果有多个主题，请提供主题目录）。
• 目标 WordPress 版本范围（theme.json 版本和功能因核心版本而异）。
• 问题出现的位置：站点编辑器、文章编辑器、前端，或所有位置。

流程

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

1. 运行排查：
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. 检测主题根目录和关键文件夹：
   • node skills/wp-block-themes/scripts/detect_block_themes.mjs

如果存在多个主题，请选择一个，并将所有更改限定在该主题根目录中。

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

如果要从头创建新区块主题（或将经典主题转换为区块主题）：

• 优先从已知可用的脚手架开始（或从 WP 环境导出），不要自行猜测文件布局。
• 明确说明支持的最低 WordPress 版本，因为 theme.json 的架构版本各不相同。

阅读：

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

创建主题根目录后，重新运行 detect_block_themes，然后继续以下步骤。

2) 确认主题类型和覆盖预期

• 区块主题的标志：
  • 存在 theme.json
  • 存在 templates/ 和/或 parts/
• 请记住样式层级：
  • 核心默认值 → theme.json → 子主题 → 用户自定义
  • 用户自定义可能导致 theme.json 编辑看起来“未生效”

阅读：

• references/debugging.md（样式层级 + 最快检查方法）

3) 安全地更改 theme.json

确定要更改的内容：

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

阅读：

• references/theme-json.md

4) 模板和模板部件

• 模板位于 templates/ 下，格式为 HTML。
• 模板部件位于 parts/ 下，且不得嵌套在子目录中。

阅读：

• references/templates-and-parts.md

5) 样板

如果需要由主题提供样板，优先使用 patterns/ 下的文件系统样板。

阅读：

• references/patterns.md

6) 样式变体

样式变体是 styles/ 下的 JSON 文件。注意：用户选择样式变体后，该选择会存储在数据库中，因此更改文件可能不会自动“更新用户看到的内容”。

阅读：

• references/style-variations.md

验证

• 站点编辑器在预期位置（样式界面、模板、样板）反映更改。
• 前端按预期呈现样式。
• 如果样式没有变化，请确认用户自定义是否覆盖了主题默认值。
• 如果涉及资源（字体、自定义 JS/CSS 构建），请运行仓库的构建/代码检查脚本。

故障模式 / 调试

从以下内容开始：

• references/debugging.md

常见问题：

• 主题根目录错误（编辑了未启用的主题）
• 用户自定义覆盖了默认值
• theme.json 结构无效/存在拼写错误，导致无法应用
• 模板/部件位于错误的文件夹中（或部件嵌套在子目录中）

升级处理

如果上游行为不明确，请查阅权威文档：

• Theme Handbook 和 Block Editor Handbook 中有关 theme.json、模板、样板和样式变体的内容。