WordPress 中的 theme.json 文件是什么以及如何使用它

您是否正在使用块主题并在 WordPress 中看到 theme.json 文件？也许您想知道这个文件的目的是什么，以及是否应该编辑它。

theme.json 文件是 WordPress 中完整站点编辑体验的关键部分。随着块主题变得越来越普遍，了解 theme.json 的作用以及如何正确编辑它非常重要。

这就是我们整理这份综合指南的原因。在本文中，我们将解释什么是 theme.json 文件以及如何使用它来自定义您的 WordPress 网站。

什么是 WordPress theme.json 文件？

theme.json 文件是 WordPress 5.8 中引入的一个特殊主题文件。它在完整的站点编辑 （FSE） 体验中起着关键作用，它允许您直观地自定义 WordPress 块主题的各个方面。

从本质上讲，theme.json 文件充当控制块主题的样式和功能的蓝图。它包含的代码告诉 WordPress 颜色、排版、布局和模板等不同元素的外观和行为。

为什么 WordPress 块主题需要 theme.json 文件？

在 WordPress 中编辑块主题与编辑经典主题不同。

经典主题使用 functions.php 文件来启用具有该功能的自定义菜单或特色图像等功能。然后，您可以使用 CSS 样式表 （style.css） 文件中的 CSS 规则设置这些功能的样式。add_theme_support()

在块主题中，theme.json充当定义块主题外观的所有内容的中心枢纽。它允许您在一个位置定义字体、颜色和布局选项等内容，从而取代了 in functions.php 的需求。add_theme_support()

这就是为什么块主题中的 functions.php 文件通常比经典主题中的等效文件小。

与以前的经典主题系统相比，拥有专用的 theme.json 文件提供了一些巨大的好处。

首先，theme.json 与 WordPress 全站编辑器携手合作。这使您可以直接在编辑器中轻松自定义主题的样式和设置，而无需接触任何代码。

此外，theme.json 旨在为开发人员和用户创造一致的体验。一些用户在需要更改主题时发现这真的很令人沮丧，因为他们必须学习全新的布局和样式选项。

使用 theme.json，切换主题变得更加顺畅，因为一切都以类似的方式组织。

最后，通过使用 theme.json，主题开发人员和用户可以随着 WordPress 继续扩展其完整的站点编辑功能，让他们的工作面向未来。

现在我们已经介绍了什么是 theme.json 文件，让我们更深入地研究这个主题。您可以使用下面的快速链接浏览本指南：

您在哪里可以找到 WordPress theme.json 文件？

theme.json 文件位于 Web 服务器上的主题目录中。典型的文件路径是 public_html » wp-content » 主题 » 你的主题名称 » theme.json。

要访问它，您首先需要通过 FTP 或托管帐户的文件管理器连接到您的站点。

如果您使用 Bluehost，则可以登录并切换到“网站”选项卡。然后，单击您网站下方的“设置”按钮。

现在，请确保留在 ‘概述’ 选项卡上。

然后，向下滚动以单击“文件管理器”按钮。

当您以这种方式打开文件管理器时，您将自动进入您网站的根文件夹。

在这里，查找 ‘wp-content’ 目录并打开它。在那里，您会找到 ‘themes’ 文件夹，其中包含您安装的所有 WordPress 主题。

打开您正在使用的特定数据块主题的文件夹。theme.json 文件将与其他主题文件一起直接位于此主题目录中。

找到它后，您可以使用代码编辑器查看 theme.json 文件。

theme.json 文件是什么样子的？

theme.json 文件具有特定的结构，用于组织 WordPress 块主题的所有全局设置。

根据模板的复杂程度或简单程度，文件可以非常短或长。但是，您可以轻松地将此文件分为 7 个顶级部分：

下面是一个简化的细分：

图式

这部分实际上是可选的，因此您可能会也可能不会在您的主题中看到它。

schema 属性将 URL 链接到 WordPress JSON 架构，该架构定义主题的全局设置、样式和其他配置。

版本

此部分指定文件使用的 theme.json 格式的 API 版本，并确保它遵循正确的结构。

在撰写本文时，API 的版本为 2。

设置

此属性定义用户可用于自定义其主题的选项和控件。其中包括主题的调色板、排版、间距、渐变、阴影、边框等的预设。

下面是一个非常简单的 settings 属性示例：

如果你看一下代码，就会发现它所使用的语言很容易理解。您可以看出这些设置定义了主题中使用的颜色、字体系列、字体大小和间距。

如果您在此处或您的主题中有任何不理解的参考资料，您可以查看官方的 WordPress 设置参考。

某些元素（如颜色和字体系列）具有 slug，如下所示：

这些将在后面的 styles 部分派上用场，以制作预设，我们将在下一部分解释。

风格

虽然 settings 部分定义主题的默认自定义选项，但 styles 部分将它们应用于主题。

在这里，您可以使用预设将自定义设置应用于整个网站或块级别。

让我们看看下面的示例：

如您所见，此代码段中出现了以下代码行：.这些是预设，它们是 styles 部分中的快捷方式，可引用 settings 部分中定义的值。var(--wp--preset--xxx)

例如，考虑 settings 部分。这里 是 slug，此颜色的相应预设是 。{"slug": "base", "color": "#ffffff", "name": "White"}"base"var(--wp--preset--color--base)

因此，styles 中的代码表示此主题的背景色为白色。"color": {"background": "var(--wp--preset--color--base)"

自定义模板

区块主题开发人员可以为自定义页面、文章或文章类型创建预定义的布局，供用户使用。

例如，Twenty Twenty-Four 主题在 theme.json 文件中定义了多个自定义模板：Page No Title、Page With Sidebar、Page with Wide Image 和 Single with Sidebar。

您可以使用其中任何一个来创建您的内容。

需要注意的一点是，theme.json 文件仅按名称引用模板，并提供有关它们的元数据，例如它们的标题和它们所适用的文章类型。

但是，自定义模板的实际外观和功能是在 theme 文件夹内的单独模板文件中定义的。

要查看它们，您可以转到 public_html » wp-content » 主题 » your-theme-name » 模板。

模板部件

模板部分是可应用于自定义模板的可重用区域。这些元素包括页眉、页脚、侧边栏等。

以下是在 theme.json 中注册的这些模板部分的外观：

与自定义模板一样，theme.json 文件仅引用模板。

它们的实际外观在 parts 文件夹中它们自己的模板零件文件中定义。

模式

模式是预制的块集合，可让您在页面、帖子或主题中的其他任何位置创建自定义内容布局。

当您打开完整的站点编辑器时，您可能会注意到 Patterns 菜单。在这里，您可以找到 Gutenberg 块主题的所有可用模式。

借助 theme.json，主题开发人员可以从公共 Pattern 目录中引用模式。这是提供更多自定义选项的好方法，而无需自己设计这些可重用的块。

例如，Twenty Twenty-Four 主题引用了官方目录中的两种模式：三列服务和客户端部分：

我们知道这一点，因为这些模式位于完整站点编辑器的 Patterns 菜单中。

但是，它们不在 theme 目录内的 patterns 文件夹中。

编辑 theme.json 文件之前应该做什么

由于 theme.json 是一个核心主题文件，因此直接在您的实时 WordPress 网站上编辑它会带来一些风险。意外错误可能会破坏您的主题或网站。

更安全的方法是使用子主题。

子主题继承了父主题（您正在使用的块主题）的所有样式和功能，但允许您在不修改父主题本身的情况下进行自定义。这样，如果父主题收到更新，您的自定义设置就不会被覆盖。

您可以阅读我们的指南 如何在 WordPress 中创建子主题 了解更多信息。本文介绍了一种使用 Create Block Theme 插件的简单方法，该方法将仅为您的子主题自动生成一个新的 theme.json 文件。

为了确保流畅的编辑体验并避免任何网站停机，我们还建议您为您的 WordPress 网站创建一个新备份。这样，如果出现问题，您可以轻松地将网站恢复到以前的状态。

我们建议使用像 Duplicator 这样的插件来获得快速可靠的备份解决方案。

还建议在本地 WordPress 开发环境或暂存站点中工作。这将创建您的实时网站的副本，您可以在其中安全地测试更改，而不会影响您的访问者。

以下是一些需要牢记的提示：

• 从 theme.json 文件中的细微编辑开始，并在进行更复杂的更改之前对其进行全面测试。
• 如果您不确定 theme.json 文件中的任何特定属性或设置，请查阅官方 WordPress 文档。
• 如果您遇到任何问题，请随时向主题开发者的支持团队或 WordPress.org 支持论坛寻求帮助。查看我们的指南，了解如何寻求 WordPress 支持以获取更多信息。

如何编辑 WordPress theme.json 文件

根据我们的研究和测试，我们发现了两种编辑 WordPress theme.json 文件的方法：使用全站编辑器或使用代码。第一个选项更容易、更安全，可让您从网站的前端查看您的修改。

同时，如果您对高级 WordPress 开发感到满意，建议使用第二种选择。

不使用代码编辑 theme.json （初学者）

要在不直接接触代码的情况下编辑 theme.json 文件，您可以使用 Create Block Theme 插件。该插件由官方 WordPress.org 团队发布，允许用户创建、编辑和保存其块主题的样式变体。

首先，在您的管理区域安装 WordPress 插件。然后，转到 Appearance » Editor 打开全站编辑器。

您现在将看到几个用于编辑主题的菜单。

在这里，选择“样式”。

接下来，单击铅笔图标 ‘Edit styles’ 图标。

这将带您进入块编辑器以编辑您网站的全局样式。

现在，您可以像往常一样更改主题的样式。有关更多信息，您可以在我们的 WordPress 全站编辑指南中阅读有关如何编辑主题的全局样式的部分。

让我们尝试创建自定义调色板作为示例。

颜色方案或调色板是文本、背景和按钮等元素的一组默认颜色。它确保整个网站的外观有凝聚力。

使用相同颜色预设的元素将始终匹配，以便您的网站设计看起来精美而专业。

要编辑调色板，请在 Styles settings 侧边栏上选择 ‘Colors’。

在下一个屏幕上，您将看到一些用于自定义主题颜色的设置。

在这里，单击 ‘Palette’ 部分中的颜色。

在此示例中，Twenty Twenty-Four 主题已在调色板中定义了 5 种颜色，但您可以更改其中任何一种颜色以从头开始创建自定义颜色。

为此，请单击“主题”下的一种颜色。然后，在颜色选取器工具中选择任何颜色。

现在，如果您预览您的网站，您将看到使用先前颜色的特定块或元素已替换为您刚刚在调色板中选择的颜色。

您可以对每种颜色重复相同的步骤。然后，点击“保存”。

保存更改后，单击 Create Block Theme 按钮（扳手图标）。

然后，选择“将更改保存到主题”。

在下一个屏幕上，您需要向下滚动。

之后，单击“保存更改”。这将提示 WordPress 将您对主题所做的所有更改存储在 theme.json 文件中。

完成此操作后，块编辑器将自行刷新。

现在，再次单击“创建块主题”按钮并选择“查看theme.json”。

要查看自定义调色板的代码，请查找嵌套在 and 中的 that，如下所示：palettecolorsettings

在它下面，您应该会看到自定义调色板的新十六进制代码。

使用代码编辑 theme.json （高级用户）

如果您是有抱负的 WordPress 主题开发人员或有一定的代码经验，建议使用此方法。

首先，在 WordPress 目录中打开块主题的 theme.json 文件。您可以使用 Web 主机文件管理器中的代码编辑器，也可以下载文件，在计算机上编辑它，然后将其上传回您的服务器。

我们将使用 Twenty Twenty-Four 主题和 Bluehost 的文件管理器进行演示。如果您是 Bluehost 用户并且正在使用文件管理器，那么您只需右键单击您的 theme.json 文件，然后单击“编辑”。

如果您使用 FTP，那么您可以阅读我们的指南，了解如何使用 FTP 将文件上传到 WordPress。

让我们尝试一个编辑 theme.json 文件的简单示例：创建自定义字体大小。

同样，请记住，settings 属性指定主题的默认样式，而 styles 属性实现它们。因此，我们将编辑 theme.json 文件中的 settings 属性。

如果您使用子主题，则只需将以下代码复制并粘贴到 theme.json 文件中，然后根据需要更改字体大小（以像素为单位）：

注意： 如果您直接编辑父主题的文件，则需要找到显示 .fontSizes

它应该嵌套在 and 中，如下所示：typographysettings

之后，将这些代码行替换为上面的代码片段。只需确保其中没有语法错误。

完成后，保存文件并预览您的网站以查看您的更改。对于 Bluehost 用户，您只需在文件管理器的代码编辑器中单击“保存更改”即可。

如果您想进一步编辑theme.json，我们强烈建议您更熟悉文件的结构，如上一节所述。

我们还建议您阅读官方 WordPress 设置参考，其中包括可用设置属性的完整列表以及使用它们的说明。

额外提示：使用 WPCode 将自定义代码添加到您的主题

在本指南中，您了解了 theme.json 及其在主题自定义方面的潜力。但也许直接编辑仍然感觉有点不知所措。

幸运的是，还有另一个用户友好的选项可用于添加自定义代码和进行高级自定义：WPCode。

使用 WPCode，您可以插入自定义代码片段，而无需接触主题文件本身。这大大降低了在自定义过程中破坏网站的风险。

如果您想了解有关此代码片段插件的更多信息，请查看我们的完整 WPCode 评论。

此外，这里有一些有用的教程可以帮助您开始使用 WPCode：

• 适合初学者的有用 WordPress 代码片段（专家精选）
• 如何在 WordPress 中为回头客突出显示新帖子
• 如何在 WordPress 中突出显示文本
• 如何在 WordPress 中轻松添加框阴影

我们希望本文能帮助您了解 WordPress 中的 theme.json 文件。您可能还想查看我们关于如何编辑 WordPress 网站的初学者指南和我们专家精选的 WordPress 最佳拖放页面构建器。