释放theme.json的威力：像专业人士一样定制WordPress主题

随着 WordPress 生态系统的不断发展，WordPress 开发人员拥有了比以往更多的控制权。全站编辑（FSE）为所有用户提供了从头开始创建主题的机会，尤其是在使用 theme.json 文件时。

开发人员也可以利用 theme.json 文件。该配置文件允许对 WordPress 主题进行细粒度定制，而无需使用更复杂的编程语言进行繁琐复杂的操作。

在本综合指南中，我们将探讨 theme.json 文件的作用，包括它与完整网站编辑的关系。到最后，无论你的开发能力如何，你都会了解如何利用它的功能来创建现代化的高性能网站。

theme.json 文件介绍

theme.json 文件的核心是一个配置文件，用于定义 WordPress 主题的设置和样式。它使用 JavaScript Object Notation (JSON)，这是一种结构化数据，继承了其父语言的键值配对，方便你编写代码。

JSON 代码示例。

theme.json 文件是控制主题各个方面的关键。其中包括调色板、排版设置、布局选项、每个区块的样式、自定义 CSS 属性等。我们将在本文中详细介绍这些方面。

虽然到目前为止这听起来并不太革命性，但 theme.json 对 WordPress 开发的未来非常重要。下一节将解释原因。

为什么 theme.json 与 WordPress 主题开发相关？

WordPress 的典型主题开发和插件创建方法通常围绕使用 PHP 编辑模板文件、使用 functions.php 文件和其他技术任务展开。

theme.json文件标志着一个重大转变，尤其是在开发主题方面。原因有以下几点：

• 该文件是定义主题设置和样式的单一、有序的位置。这减少了对分散的 CSS 和 PHP 文件的需求。
• 在theme.json 中集中声明样式和设置意味着 WordPress 可以生成更有效的 CSS。与使用 jQuery 等框架相比，WordPress 有可能提高性能。
• 与以往相比，您对网站和各个区块的样式有更多的控制权。这使技术知识较少的用户也能进行主题开发。
• 随着 FSE 的不断发展，theme.json 文件将在主题、全局样式和区块编辑器的交互方式中发挥至关重要的作用。

将所有这些方面结合起来，就能以标准化的方式为主题定义设置和样式。对于希望了解和使用不同主题的人来说，使用 theme.json 将使您创建的 WordPress 主题更加强大、灵活和用户友好。更好的是，这些创建将与平台的未来发展方向保持一致。

在哪里找到 theme.json 文件

首先，在 “传统” 或 “经典” 主题中找不到 theme.json 文件。要找到并使用该文件，你需要一个专用的区块主题。不过，只要运行的是 WordPress 5.8 或更高版本，您可以在任何主题中创建该文件。

theme.json 文件的典型位置是wp-content/themes/[你的主题]。如果文件不在那里，你应该打开你最喜欢的编码编辑器，根据需要创建文件。暂时不用担心文件内容，我们很快就会讨论这个问题。

如果您需要从头开始创建一个新文件，但又想在定制自己的文件前了解其中的复杂内容，请查看默认的 Twenty Twenty-Four 主题。

作为一个块主题，它将有一个 theme.json 文件可供查看。在接下来的几节中，我们将介绍该文件的结构，打开它可能会派上用场。

使用 theme.json 所需的信息

当然，并不是每个人都能打开配置文件并开始工作。你仍然需要一些基本技能和知识来构建和定制主题：

• 基本的 JSON 知识。我们认为这是你可以快速掌握的，但熟悉 JSON 语法和结构仍然至关重要。
• 了解 CSS。您会发现，许多 theme.json 对象和属性都与 CSS 对应。CSS “chops” 在这里将大有裨益。
• WordPress 区块编辑器知识。了解块是如何工作的，以及它们的自定义选项，会对您的构建工作有所帮助。

虽然这并不是绝对必要的，但我们鼓励你至少了解 FSE 的关键概念，这将有助于你以更有效的方式利用 theme.json 文件。您还可以了解您的编辑将如何影响最终用户的 “修补”。此外，在某些情况下，你仍然需要使用 HTML 和 JavaScript 来实现你的设想。

最后，我们向您推荐几款技术 “额外装备”：

• 代码编辑器。选择一个能提供 JSON 语法高亮和验证功能的高质量编辑器，将使您的工作流程更加轻松愉快。
• 本地开发环境。使用本地环境工具对主题进行开发，可以让您快速试验和测试更改，而不会影响实时网站。

有了这些工具和知识，您就可以开始使用 theme.json 自定义 WordPress 主题了。

了解 theme.json 的结构和层次结构

显然，theme.json 文件有一个你需要了解的结构。它还有一个层次结构，以及一些需要进一步解释的独特元素。

这可能是使用配置文件最复杂的部分，但即便如此，你也能轻松掌握其中的概念。

让我们先从结构开始，然后了解 theme.json 的其他元素。

基本结构

鉴于文件采用 JSON 格式，你可能已经了解了结构的一般概念。首先，整个文件对象都用大括号包起来，文件中的其他对象也是如此。每个对象都由键值对组成，键值使用单引号或双引号，行尾使用逗号。

一个 theme.json 文件至少需要 version, settings, 和 styles 对象：

{
"version": 2,
"settings": {
// Global settings go here
},
"styles": {
// Global styles go here
}
}

settings 和 styles 对象简单明了，但 version 需要更多解释。该值将是一个整数，与读取文件时使用的 API 版本相匹配。当前的 API 版本是3，不过2版本也很常见，你也可以从旧版本迁移过来。

大多数 theme.json 文件结构还包括一个 schema。简而言之，它可以让你在代码编辑器中使用自动完成功能，并为文件提供验证。你可以在文件的顶部添加这一内容：

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

从这里开始，你将为 settings 和 styles 添加各种属性和对象，以构建你的文件。

层次结构

theme.json 文件遵循层次结构，只是网站 settings 和 styles 整体层次结构中的一个层次。如果你有 CSS 知识，理解起来会更容易，因为该文件的复杂程度与 CSS 类似。

简而言之，您对 theme.json 所做的自定义不一定会显示在网站前端。用户配置优先于一切。这意味着在 WordPress 的外观>编辑器界面上进行的任何更改都会显示在前端：

WordPress 的主网站编辑器界面。

如果您使用的是子主题并包含一个 theme.json 文件，那么它将覆盖除网站编辑器之外的所有更改。同样，你在父主题配置文件中定义的任何内容都将覆盖 WordPress 的默认设置和样式。虽然 WordPress 也有自己的 theme.json 文件，但我们在这篇文章中重点讨论的就是这个文件。

虽然这不是这篇文章的重点，但你也可以使用钩子和过滤器来覆盖值。通过这些动态过滤器，你可以创建插件和主题，同时改变主题和平台设置及样式。

区块语法

如果你进入 WordPress 区块或站点编辑器，打开一篇文章或一个页面，然后切换代码编辑器，你会发现内容中有很多看似 HTML 注释的内容：

WordPress 区块编辑器中的代码编辑界面。

这是因为区块主题不是使用 PHP 文件，而是使用 HTML 文件以及注释和区块标记来创建网站。这些元素的组合产生了您在编写 theme.json 文件时所需的 “区块语法”。

对于包含内容的区块，例如段落区块，你需要对内容进行包装：

<!-- wp:paragraph -->
<p>Content goes here!</p>
<!-- /wp:paragraph -->

在其他情况下，你只需要单行注释或自动关闭的注释。对于某些区块，你可以组合类型来创建布局和设计。您还可以嵌套这些注释：

<!-- wp:columns -->
<div class="wp-block-columns">
<!-- wp:column -->
<div class="wp-block-column"></div>
<!-- /wp:column -->
<!-- wp:column -->
<div class="wp-block-column"></div>
<!-- /wp:column -->
</div>
<!-- /wp:columns -->

在这里，我们使用封装注释创建一个列块。在其中，我们可以开始添加 HTML 来设计这些列，并包含各个列的包装器。这在前端是很容易做到的，因为你经常会把区块放在彼此的内部。

要查找特定块的标记，可以在区块编辑器手册中查找，直到找到所需内容。不过，最简单的方法是将区块添加到 WordPress，打开代码编辑器，然后从那里复制标记。

至于如何修改标记，我们将在后面的章节中介绍。

theme.json 与 WordPress 全站编辑如何结合

通过对层次结构的讨论，你会明白 theme.json 是 FSE 的重要组成部分。两者共同为 WordPress 提供全面的主题解决方案。例如，全局样式界面基本上就是 theme.json 设置的可视化呈现。

网站编辑器侧边栏显示主题的全局样式选项。

您可以在全局样式面板或配置文件中修改设置，WordPress 会根据需要更新相应的值。虽然网站编辑器设置优先，但theme.json 将作为主题自身样式的基础。对于最终用户来说，全局样式可以让他们用自己的自定义样式替换默认样式，而无需代码或编辑 theme.json 文件。

此外，您在 theme.json 文件中定义的 CSS 自定义属性也可在全局样式界面中使用。这样，用户就可以利用这些属性在整个网站上创建更一致的样式。这还可以扩展到定义特定的区块样式和设置，你可以在 WordPress 仪表板上进一步调整。

简而言之，theme.json  提供了对设置、样式等更细粒度的控制。与传统方法相比，它是一种开发人员级别的工具，能提供更直接、更简化的体验。相比之下，全局样式界面让每个人都有机会按照自己的喜好自定义主题。在进一步开发主题的过程中，你会发现两者是如何协同工作，帮助创建网站设计和布局的。

使用 theme.json 文件属性

了解了基础知识后，你就可以开始使用 theme.json 文件中的对象和属性了。我们无法涵盖所有的使用情况或可能性。不过，在本教程结束时，您将能够创建功能齐全、前端美观的主题。

Settings

settings 属性可让你控制网站编辑器中提供的功能及其行为方式。这是一个顶级属性，通常会有多层嵌套。

一旦我们了解了样式及其变化，你就会发现这些选项之间有一些交叉，但这两种类型在创建主题时都有作用。

你可以选择一定数量的属性：

{
"version": 3,
"settings": {
"appearanceTools": false,
"blocks": {},
"border": {},
"color": {},
"custom": {},
"dimensions": {},
"layout": {},
"position": {},
"shadow": {},
"spacing": {},
"typography": {},
"useRootPaddingAwareAlignments": false
}
}

官方的《WordPress 主题开发人员手册》包含所有这些设置（和样式）的参考资料。不过，以下是几个需要进一步说明的重要设置的简要概述：

• appearanceTools。这个包罗万象的属性可以启用许多其他属性，是为了节省时间。它可以设置边框选项、排版线高、填充、页边距等。
• blocks。虽然你的大部分工作都将着眼于全局设置和样式，但 blocks 属性可以让你在每个块的基础上进行设置。我们不会在此详细介绍这一概念，但《主题开发者手册》中有关于 theme.json 这方面的出色文档。
• custom。这个独特的属性没有任何功能，它的作用由你决定。你可以用它为主题创建自定义 CSS 属性，而且范围很广。
• useRootPaddingAwareAlignments. 同样，这是一个复杂的属性，我们不会全面介绍。从本质上讲，它可以帮助你放置主题的水平填充样式，而且功能强大。如果你想让全宽项目延伸到屏幕边缘，同时在根元素上使用填充，就可以使用它。

请注意，你不需要在 theme.json 中添加任何你不想使用的属性。例如，如果你不想使用 appearanceTools，你可以直接将其省略，而不是定义为 false。

如何在 theme.json 中定义设置

在定义设置时，每个属性都有许多键值对子属性。例如，你可以这样创建调色板：

{
"version": 3,
"settings": {
"color": {
"palette": [
{
"color": "#0073aa",
"name": "Primary",
"slug": "primary"
},
{
"color": "#23282d",
"name": "Secondary",
"slug": "secondary"
}
],
…

其他属性具有简单的布尔值，可在网站编辑器中打开或关闭这些功能：

{
"version": 3,
"settings": {
"color": {
"background": true,
"defaultPalette": true,
"link": true,
"text": true
}
}
}

一旦定义了设置，就可以为其引入样式。现在就让我们来看看。

样式和样式变化

settings 定义了某些样式选项的访问权限，而 styles 属性则可以让你为主题定义全局样式。同样，这是一个使用多层嵌套的顶级属性。你可以针对特定元素、区块，甚至使用自定义 CSS 属性。

在这里定义主题样式非常重要，这样你就可以在网站编辑器中访问和自定义它们。您可以使用多种元素：

{
"version": 3,
"styles": {
"border": {},
"color": {},
"dimensions": {},
"filter": {},
"shadow": {},
"spacing": {},
"typography": {},
"css": {}
}
}

不过，这些二级属性中的很多都不会经常使用。相反，有些属性主要用于区块或元素。例如

…
"styles": {
"blocks": {
"core/group": {
"color": {
"text": "#000000",
"background": "#ffffff",
"link": "#777777"
}
…

对于全局样式，你将在根目录下工作，也就是页面的 <body> 标签。对于特定元素，可以采用与块类似的结构，这次使用的是 elements 属性：

…
"styles": {
"elements": {
"button": {
"color": {
"text": "#ffffff",
"background": "#aa3f33"
}
…

如果您在网站编辑器中查看您所做的任何更改，就会发现它们已经到位。标记还将为您创建的任何样式生成 CSS：

显示浏览器 DevTools 的网站前端，突出显示为元素生成的 CSS。

请注意，您还可以为元素设置伪类样式，如悬停和焦点样式：

…
"elements": {
"button": {
"color": {
"text": "#ffffff",
"background": "#aa3f33"
},
":hover": {
"color": {
"background": "#822f27"
}
…

样式的应用比这还要深入，这也是使用 theme.json 的一大优点。

风格变化

在我们继续之前，你需要了解一下风格变化。你可以在 FSE 界面中看到这些不同的调色板和排版样式：

网站编辑器中的 “样式” 侧边栏，显示不同的变化。

不过，这些并不是你在 theme.json 中编写的代码。相反，你需要创建不同版本的文件，给它们一个唯一的名称，并将它们存储在主题的样式目录中：

显示样式变化 JSON 文件的代码编辑器。

请注意，标记中的标题对每个备选 JSON 文件都是唯一的。不过，这是一个可选字段，不过我们建议您使用它，以获得清晰度和最佳体验。

自定义模板和模板部分

与样式变化一样，theme.json 也允许你注册自定义模板和相关模板部分。注册标记非常简单：

"customTemplates": [
{
"name": "my-template",
"title": "My Template",
"postTypes": [
"page",
"post"
]
}
]

customTemplates 属性需要定义三个元素：

• name。这将对应于你在主题模板目录中创建的模板，如/template/my-template.html。
• title。这是模板名称的可读版本。
• postTypes。如果没有定义，默认为页面，但可以指定模板适用的文章类型数组。

用户可以在网站或区块编辑器中选择您注册的任何模板：

在 WordPress 网站编辑器中选择编辑、交换、创建或显示模板。

说到模板部件，您不需要注册它们，但我们建议您注册。其结构与注册模板类似：

…
"templateParts": [
{
"area": "header",
"name": "header",
"title": "Header"
},
…

在这里，名称和标题与完整模板的定义相同。区域与部件所属的位置有关：默认为 header, footer, 或 uncategorized ，但您可以将模板部件分配到任何自定义区域。

我们建议你也研究一下如何显示这些模板部分，因为如果没有一些额外的编码，它们是不会显示出来的。即便如此，注册它们也很简单。

样板

最后，让我们来讨论一下区块模式。你可以在 theme.json 文件中使用一个顶级数组捆绑任意数量的模式。WordPress 样板库中任何合适的模式都可以包含在你的文件中：

WordPress 样板库。

定义数组非常简单：使用 patterns 属性和库 URL 中相关模式的标题即可：

从网络浏览器的 URL 中选择样板的 slug。

有了这个 slug，就可以填充 patterns 标记：

{
"version": 3,
"patterns": [
"fullwidth-vertically-aligned-headline-on-right-with-description-on-left"
]
}

您可以在区块编辑器样板目录中选择它们：

区块编辑器中的 WordPress 样板目录。

这种将样板库资产引入主题的简单方法既方便又有价值。这也是 theme.json 文件迅速成为 WordPress 主题开发者最喜欢的构建方式的另一个原因。

使用 theme.json 定制 WordPress 网站的工作流程

了解 theme.json的关键组件后，制定使用 theme.json 的工作流程就是重要的一步。它代表了一种开发主题的新方法，因此需要以不同于传统方法的方式来处理。

我们的方法是设置模式 URL，选择 API 版本，并首先定义全局设置。这包括调色板、排版选项和布局设置。在大多数情况下，激活 appearanceTools 也是有益的：

"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"appearanceTools": true,
"color": {
"palette": [
{
"name": "Primary",
"slug": "primary",
"color": "#0073aa"
},
{
"name": "Secondary",
"slug": "secondary",
"color": "#23282d"
}
]
},
"typography": {
"fluid": true,
"fontSizes": [
{
"size": "13px",
"slug": "small",
"name": "Small"
},
{
"size": "16px",
"slug": "normal",
"name": "Normal"
…

接下来，您可以使用定义的 slug 创建自定义 CSS 属性。例如，您可能已经创建了自定义 fontWeight：

…
"custom": {
"fontWeight": {
"light": 300,
"regular": 400,
"medium": 500,
"bold": 700
},
…

完成设置后，就可以指定样式了。

…
"styles": {
"color": {
"background": "var(--wp--preset--color--base)",
"text": "var(--wp--preset--color--main)"
},
…

接下来是自定义区块样式，这可能会占theme.json 文件的很大一部分。

…
"styles": {
"block": {
"core/separator": {
"color": {
"text": "var(--wp--preset--color--main)"
},
"typography": {
"fontSize": "var(--wp--preset--font-size--large)"
}
},
"core/site-tagline": {
"spacing": {
"margin": {
"bottom": "20px"
}
},
"typography": {
"fontSize": "var(--wp--preset--font-size--small)"
}
},
"core/site-title": {
"typography": {
"fontSize": "var(--wp--preset--font-size--medium)",
"fontWeight": "var(--wp--custom--font-weight--semi-bold)",
"lineHeight": "var(--wp--custom--line-height--none)"
},
…

最后，您需要设计任何自定义模板和模板部件，并将其注册到 theme.json 中。这也是注册任何你想使用的 Block 模式的时候，如果有必要，还可以创建它们。

使用 theme.json 还是 WordPress 全站编辑？

鉴于 theme.json 和全站编辑之间的交叉性，您可能会问为什么要使用其中一个而不是另一个。事实上，两者适用于不同的情况，应该结合使用。

例如，在以下情况下，您可以使用 theme.json：

• 您开发主题并从头开始创建新主题。
• JSON 是一种你能理解并使用自如的语言。
• 您希望使用编程方法为主题定义默认样式和设置。
• 您想要实现的样式和设置需要比网站编辑器中的默认值更多的控制。

当然，由于 FSE 几乎完全照搬了theme.json 的功能，因此最后一点会显得比较小众。因此，在以下情况下，全站编辑对大多数用户更有意义：

• 您是一位想要定制现有主题的网站所有者。
• 您不熟悉 JSON。
• 可视化界面更适合您的定制和开发工作流程。
• 您希望快速调整，而无需大量编码。

实际上，主题需要一个配置文件来定义其基础。在此基础上，层次结构将接管一切，网站所有者可以使用 FSE 进行进一步定制。

小结

theme.json 配置文件是 WordPress 主题开发的革命性工具。它为您的主题设置和样式提供了一个集中的家园，使您能够创建更灵活、可维护和可定制的主题。

您将在 WordPress 的站点编辑器中使用该文件来完成站点的最终设计。您在 theme.json 中设置的选项将作为默认设置，最终用户将对其进行进一步自定义。好消息是，编写该文件比调整一系列 PHP 和 CSS 文件更简单，这也是 WordPress 设计的未来趋势。

关于在 WordPress 中使用 theme.json 文件，您有任何问题吗？请在下面的评论区告诉我们！