wp-block-themes

WP Block Themes

使用时机

在以下区块主题工作中使用此技能：

• 编辑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) 创建新的区块主题（如果需要）

如果你正在从头创建新的区块主题（或转换经典主题）：

• 优先从已知良好的脚手架开始（或从WordPress环境导出），而不是猜测文件布局。
• 明确最低支持的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

确定你要修改的是：

• settings（UI允许的内容）：预设、排版比例、颜色、布局、间距
• styles（默认外观）：元素/块的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

验证

• 站点编辑器在预期位置反映更改（样式UI、模板、模式）。
• 前端以预期样式渲染。
• 如果样式未更改，确认用户自定义是否覆盖了主题默认值。
• 如果涉及资源（字体、自定义JS/CSS构建），运行仓库的构建/检查脚本。

失败模式/调试

从以下开始：

• references/debugging.md

常见问题：

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

升级

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

• 主题手册和区块编辑器手册，了解theme.json、模板、模式和样式变体。