正如您在主题结构中所学到的，theme.json 是 WordPress 在您的主题中查找的标准文件。虽然它对于块主题来说并非技术上必需，但配置各种设置和样式几乎总是必要的。

本文档是关于 theme.json 是什么以及它是如何工作的快速介绍。然而，这是一个非常庞大的主题，因此有一个专门的章节来探索您可以使用它的所有功能：全局设置和样式。

theme.json 是什么？

theme.json 是一个配置文件，它告诉 WordPress 您想要启用哪些设置、如何对特定元素和块进行样式化，以及要注册哪些模板和模板部分。

您可以使用 theme.json 做一些事情：

  • 启用或禁用功能，如首字下沉、内边距、外边距和行高。
  • 添加颜色调色板、渐变、双色图和阴影。
  • 配置排版功能，如字体家族、大小等。
  • 添加 CSS 自定义属性。
  • 注册自定义模板并将部分分配给模板部分区域。

您的 theme.json 配置将反映在 WordPress 后台的帖子、模板和站点编辑器中看到的內容。特别是自定义样式将反映在样式界面中：

WordPress 站点编辑器正在查看单篇文章模板。右侧，样式界面中高亮显示了按钮块。

theme.json 结构

theme.json 文件可以只有几行代码，例如这个启用块外观工具的例子：

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"appearanceTools": true
	}
}

或者它可以是一个极其复杂的文件，跨越数千行代码。您想要配置多少功能完全取决于您。

起点是了解可以配置的最高级别属性。以下是其外观的概要：

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {},
	"styles": {},
	"customTemplates": {},
	"templateParts": {},
	"patterns": []
}

以下是这些属性定义的内容：

  • $schema: 用于定义支持的 JSON 架构，这将与许多代码编辑器集成，为您提供实时提示和错误报告。
  • version: 您正在构建的 theme.json 架构版本。最新版本是 2，始终可以在theme.json 活体参考中找到，这是一份列出您可以设置的最最新属性的文档。
  • settings: 用于定义您的块控件、颜色调色板、字体大小等。
  • styles: 用于将颜色、字体大小、自定义 CSS 等应用于网站和块。
  • customTemplates: 您在主题的 /templates 文件夹中定义的自定义模板的元数据。
  • templateParts: 您在主题的 /parts 文件夹中定义的模板部分的元数据。
  • patterns: 来自模式目录要注册的图案斜杠数组。

您将在全局设置和样式章节中了解更多关于这些属性及其子属性的信息。

设置和样式层次结构

您主题中的 theme.json 文件只是网站设置和样式配置层次结构中的一个级别。这意味着在某些情况下它可以被覆盖。

此层次结构的顺序从最低到最高是：

  • WordPress theme.json: WordPress 拥有自己的 theme.json 文件，其中定义了默认设置和样式。
  • 主题 theme.json: 您在主题的 theme.json 文件中定义的任何内容都会覆盖 WordPress 的默认值。
  • 子主题 theme.json: 如果已激活，子主题的 theme.json 将优先于主或“父”主题。
  • 用户配置: 用户可以在 WordPress 后台的外观 > 编辑器中进一步自定义其站点的工作方式，JSON 数据保存在其站点的数据库中。他们的选择优先于层次结构中的所有其他级别。

还有可用的过滤器钩子，允许插件和主题作者动态覆盖值。要了解有关这些内容的更多信息，请查看来自 WordPress 开发者博客的如何使用服务器端过滤器修改 theme.json 数据。

需要记住的重要一点是，在您的 theme.json 文件中配置的任何内容可能不会在层次结构中优先。