WordPress 中的 theme.json 文件是什么以及如何使用它
您是否使用块主题并在 WordPress 中查看 theme.json 文件？也许您想知道该文件的用途是什么以及是否应该编辑它。
theme.json 文件是 WordPress 完整站点编辑体验的重要组成部分。随着块主题变得越来越普遍，了解 theme.json 的作用以及如何正确编辑它非常重要。
这就是我们 WPBeginner 整理这份综合指南的原因。在本文中，我们将解释什么是 theme.json 文件以及如何使用它来自定义您的 WordPress 网站。
什么是 WordPress theme.json 文件？
theme.json 文件是 WordPress 5.8 中引入的特殊主题文件。它在完整的站点编辑 (FSE) 体验中发挥着关键作用，它允许您直观地自定义 WordPress 块主题的各个方面。
本质上，theme.json 文件充当控制块主题的样式和功能的蓝图。它包含的代码告诉 WordPress 不同的元素（如颜色、排版、布局和模板）应该如何外观和行为。
为什么 WordPress 块主题需要 theme.json 文件？
在 WordPress 中编辑块主题与编辑经典主题不同。
经典主题使用functions.php文件来通过add_theme_support()函数启用自定义菜单或特色图像等功能。然后，您可以使用 CSS 样式表 (style.css) 文件中的 CSS 规则设置这些功能的样式。
在块主题中，theme.json 充当定义块主题外观的所有内容的中心枢纽。它允许您在一个位置定义字体、颜色和布局选项等内容，从而无需在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 » your-theme-name » theme.json。
要访问它，您首先需要通过 FTP 或托管帐户的文件管理器连接到您的站点。
如果您使用 Bluehost，则可以登录并切换到“网站”选项卡。然后，单击网站下方的“设置”按钮。
现在，请确保停留在“概述”选项卡上。
然后，向下滚动以单击“文件管理器”按钮。
当您以这种方式打开文件管理器时，您将自动进入网站的根文件夹。
在这里，找到“wp-content”目录并打开它。在那里，您会找到“主题”文件夹，其中包含所有已安装的 WordPress 主题。
打开您正在使用的特定块主题的文件夹。 theme.json 文件将与其他主题文件一起直接位于此主题目录中。
找到它后，您可以使用代码编辑器查看 theme.json 文件。
theme.json 文件是什么样的？
theme.json 文件具有特定的结构，用于组织 WordPress 块主题的所有全局设置。
根据您的主题看起来的复杂或简单程度，文件可以很短或很长。但是，您可以轻松地将这个文件分为 7 个顶级部分：
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {},
"styles": {},
"customTemplates": {},
"templateParts": {},
"patterns": []
}
这是一个简化的细分：
架构
这部分实际上是可选的，可以在块主题中包含，因此您可能会也可能不会在您的主题中看到它。
schema 属性将 URL 链接到 WordPress JSON 架构，该架构定义主题的全局设置、样式和其他配置。
版本
此部分指定文件正在使用 theme.json 格式的 API 版本，并确保其遵循正确的结构。
截至撰写本文时，该 API 的版本为 2。
设置
此属性定义用户可用于自定义其主题的选项和控件。其中包括主题调色板、版式、间距、渐变、阴影、边框等的预设。
这是设置属性的一个非常简单的示例：
{
"settings": {
"color": {
"palette": [
{
"slug": "base",
"color": "#ffffff",
"name": "White"
},
{
"slug": "contrast",
"color": "#222222",
"name": "Dark"
},
{
"slug": "accent",
"color": "#f08080",
"name": "Pink"
},
{
"slug": "accent-2",
"color": "#90ee90",
"name": "Light Green"
},
{
"slug": "accent-3",
"color": "#e0ffff",
"name": "Light Blue"
}
]
},
"typography": {
"fontFamilies": [
{
"fontFamily": "Open Sans, sans-serif",
"slug": "open-sans",
"name": "Open Sans"
},
{
"fontFamily": "Arial, sans-serif",
"slug": "arial",
"name": "Arial"
},
{
"fontFamily": "Times New Roman, serif",
"slug": "times-new-roman",
"name": "Times New Roman"
}
],
"fontSizes": [
{
"name": "Extra Small",
"slug": "xx-small",
"size": "0.75rem"
},
{
"name": "Small",
"slug": "small",
"size": "0.875rem"
},
{
"name": "Medium",
"slug": "medium",
"size": "1rem"
},
{
"name": "Large",
"slug": "large",
"size": "1.125rem"
},
{
"name": "Extra Large",
"slug": "x-large",
"size": "1.25rem"
},
{
"name": "XX-Large",
"slug": "xx-large",
"size": "1.5rem"
}
],
"spacing": {
"units": ["rem"],
"values": {
"small": "1rem",
"medium": "1.5rem",
"large": "2rem"
}
}
}
}
}
如果您查看代码，就会发现所使用的语言非常容易理解。您可以看出这些设置正在定义主题中使用的颜色、字体系列、字体大小和间距。
如果这里或您的主题中有任何您不明白的参考，您可以查看官方的 WordPress 设置参考。
某些元素（例如颜色和字体系列）具有符号，如下所示：
{
"settings": {
"color": {
"palette": [
{
"slug": "base",
"color": "#ffffff",
"name": "White"
},
这些将在稍后的样式部分进行预设时派上用场，我们将在下一部分中解释。
样式
虽然设置部分定义了主题的默认自定义选项，但样式部分将它们应用于主题。
在这里，您可以使用预设将自定义设置应用到整个网站或块级别。
让我们看看下面的例子：
{
"settings": {
// Existing settings from the previous example
},
"styles": {
"color": {
"background": "var(--wp--preset--color--base)",
"text": "var(--wp--preset--color--contrast)"
},
"elements": {
"link": {
"color": {
"text": "var(--wp--preset--color--accent-2)"
}
},
"h1": {
"fontSize": "var(--wp--preset--font-size--xx-large)",
"lineHeight": "1.2",
"marginBottom": "1rem"
},
"h2": {
"fontSize": "var(--wp--preset--font-size--x-large)",
"lineHeight": "1.2",
"marginBottom": "1rem"
},
"h3": {
"fontSize": "var(--wp--preset--font-size--large)",
"lineHeight": "1.2",
"marginBottom": "1rem"
}
}
}
}
如您所知，此代码段中出现了这行代码： var(--wp--preset--xxx) 。这些是预设，它们是样式部分中的快捷方式，可引用设置部分中定义的值。
例如，请考虑设置部分中的 {"slug": "base", "color": "#ffffff", "name": "White"}。这里，“base”是 slug，该颜色对应的预设是 var(--wp--preset--color--base) 。
因此，styles 中的代码 "color": {"background": "var(--wp--preset--color--base)" 表示该主题的背景色为白色。
自定义模板
块主题开发人员可以为自定义页面、帖子或帖子类型创建预定义布局以供用户使用。
例如，“二十二十四”主题在 theme.json 文件中定义了多个自定义模板：“无标题页面”、“带侧边栏的页面”、“带宽图像的页面”和“带侧边栏的单页”。
您可以使用其中任何一个来创建您的内容。
],
"customTemplates": [
{
"name": "page-no-title",
"postTypes": ["page"],
"title": "Page No Title"
},
{
"name": "page-with-sidebar",
"postTypes": ["page"],
"title": "Page With Sidebar"
},
{
"name": "page-wide",
"postTypes": ["page"],
"title": "Page with wide Image"
},
{
"name": "single-with-sidebar",
"postTypes": ["post"],
"title": "Single with Sidebar"
}
]
需要注意的一件事是 theme.json 文件仅按名称引用模板并提供有关它们的元数据，例如它们的标题和它们所针对的帖子类型。
但是，自定义模板的实际外观和功能是在主题文件夹内的单独模板文件中定义的。
要查看它们，您可以转到 public_html » wp-content » 主题 » your-theme-name » 模板。
模板部分
模板部分是可重复使用的区域，您可以在自定义模板中应用它们。这些元素包括页眉、页脚、侧边栏等。
以下是在 theme.json 中注册的这些模板部分的样子：
"templateParts": [
{
"area": "header",
"name": "header",
"title": "Header"
},
{
"area": "footer",
"name": "footer",
"title": "Footer"
},
{
"area": "sidebar", // Removed "uncategorized"
"name": "sidebar",
"title": "Sidebar"
},
{
"area": "post-meta", // Removed "uncategorized"
"name": "post-meta",
"title": "Post Meta"
}
]
与自定义模板一样，theme.json 文件仅引用模板。
它们的实际外观在 parts 文件夹中自己的模板零件文件中定义。
模式
模式是预制的块集合，可让您在页面、帖子或主题中的任何其他位置创建自定义内容布局。
当您打开完整的站点编辑器时，您可能会注意到“模式”菜单。您可以在这里找到适合您的古腾堡块主题的所有可用模式。
通过 theme.json，主题开发人员可以从公共 Pattern 目录引用模式。这是提供更多自定义选项的好方法，而无需自己设计这些可重用的块。
例如，二十二十四主题引用了官方目录中的两种模式：三列服务和客户端部分：
"patterns": [
"three-columns-of-services",
"clients-section"
]
我们知道这一点是因为这些模式位于完整站点编辑器的“模式”菜单中。
但是，它们不在主题目录内的 patterns 文件夹中。
注意：您可能会注意到主题目录中的模板、部件和模式文件夹包含 theme.json 中未指定的文件，但它们在完整站点编辑器中仍然可见。
如果您很好奇，这是因为 WordPress 设计为根据命名约定和主题目录中的位置自动识别和使用这些文件夹。
编辑 theme.json 文件之前应该做什么
由于 theme.json 是核心主题文件，因此直接在实时 WordPress 网站上编辑它会带来一些风险。意外错误可能会破坏您的主题或网站。
更安全的方法是使用儿童主题。
子主题继承父主题（您正在使用的块主题）的所有样式和功能，但允许您自定义内容而无需修改父主题本身。这样，如果父主题收到更新，您的自定义设置将不会被覆盖。
您可以阅读我们关于如何在 WordPress 中创建子主题的指南以获取更多信息。本文展示了使用创建块主题插件的简单方法，该插件将自动为您的子主题生成一个新的 theme.json 文件。
为了确保流畅的编辑体验并避免任何网站停机，我们还建议为您的 WordPress 网站创建新的备份。这样，如果出现问题，您可以轻松地将站点恢复到之前的状态。
我们建议使用像 Duplicator 这样的插件来获得快速可靠的备份解决方案。
还建议在本地 WordPress 开发环境或临时站点中工作。这将创建您的实时网站的副本，您可以在其中安全地测试更改，而不会影响访问者。
以下是一些需要记住的提示：
首先对 theme.json 文件进行较小的编辑，并在进行更复杂的更改之前对其进行彻底测试。
如果您不确定 theme.json 文件中的任何特定属性或设置，请参阅 WordPress 官方文档。
如果遇到任何问题，请随时向主题开发人员支持团队或 WordPress.org 支持论坛寻求帮助。请查看我们关于如何寻求 WordPress 支持的指南以获取更多信息。
如何编辑 WordPress theme.json 文件
根据我们的研究和测试，我们发现了两种编辑 WordPress theme.json 文件的方法：使用全站编辑器或使用代码。第一个选项更容易、更安全，让您可以从网站的前端看到您的修改。
同时，如果您熟悉高级 WordPress 开发，建议您选择第二种。
无需代码即可编辑 theme.json（初学者）
要编辑 theme.json 文件而不直接接触代码，您可以使用创建块主题插件。该插件由 WordPress.org 官方团队发布，允许用户创建、编辑和保存其块主题的样式变体。
首先，继续在您的管理区域安装 WordPress 插件。然后，转到外观»编辑器打开全站点编辑器。
您现在将看到几个用于编辑主题的菜单。
在这里，选择“样式”。
接下来，单击铅笔“编辑样式”图标。
这将带您进入块编辑器来编辑网站的全局样式。
现在，您可以像平常一样更改主题的样式。您可以在我们的 WordPress 全站编辑指南中阅读有关如何编辑主题的全局样式的部分，以获取更多信息。
让我们尝试创建自定义调色板作为示例。
配色方案或调色板是文本、背景和按钮等元素的一组默认颜色。它确保整个网站的外观具有凝聚力。
使用相同颜色预设的元素将始终匹配，使您的网站设计看起来优雅且专业。
要编辑调色板，请选择样式设置侧栏上的“颜色”。
在下一个屏幕上，您将看到一些用于自定义主题颜色的设置。
在这里，单击“调色板”部分中的颜色。
在此示例中，二十二十四主题已在调色板中定义了 5 种颜色，但您可以更改其中任何一种颜色以从头开始创建自定义颜色。
为此，请单击“主题”下的一种颜色。然后，在颜色选择器工具中选择任何颜色。
现在，如果您预览网站，您将看到使用先前颜色的特定块或元素已被替换为您刚刚在调色板中选择的颜色。
您可以对每种颜色重复相同的步骤。然后，点击“保存”。
保存更改后，单击“创建块主题”按钮（扳手图标）。
然后，选择“保存对主题的更改”。
在下一个屏幕上，您需要向下滚动。
之后，单击“保存更改”。这将提示 WordPress 将您对主题所做的所有更改存储在 theme.json 文件中。
完成此操作后，块编辑器将自行刷新。
现在，再次单击“创建块主题”按钮并选择“查看 theme.json”。
要查看自定义调色板的代码，请查找嵌套在 color 和 settings 内的 palette，如下所示：
"settings": {
// Some code...
"color": {
// Some code...
"palette":
}
}
在其下方，您应该会看到自定义调色板的新十六进制代码。
使用代码编辑 theme.json（高级用户）
如果您是一名有抱负的 WordPress 主题开发人员或具有一定的代码经验，建议您使用此方法。
首先，在 WordPress 目录中打开块主题的 theme.json 文件。您可以使用网络主机文件管理器中的代码编辑器，也可以下载文件，在计算机上进行编辑，然后将其上传回服务器。
我们将使用 Twenty Twenty-Four 主题和 Bluehost 的文件管理器进行演示。如果您是 Bluehost 用户并且正在使用文件管理器，那么您只需右键单击 theme.json 文件并单击“编辑”即可。
如果您使用 FTP，那么您可以阅读我们有关如何使用 FTP 将文件上传到 WordPress 的指南。
让我们尝试一个编辑 theme.json 文件的简单示例：创建自定义字体大小。
再次请记住，settings 属性指定主题的默认样式，而 styles 属性则实现它们。因此，我们将编辑 theme.json 文件中的设置属性。
如果您使用子主题，则只需将以下代码复制并粘贴到 theme.json 文件中，然后根据需要更改字体大小（以像素为单位）：
{
"settings": {
"typography": {
"fluid": false,
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "16px"
},
{
"name": "Medium",
"slug": "medium",
"size": "24px"
},
{
"name": "Large",
"slug": "large",
"size": "40px"
},
{
"name": "Extra Large",
"slug": "x-lagrge", // Typo fixed (large -> large)
"size": "48px"
}
]
}
}
}
注意：如果您直接编辑父主题的文件，则需要找到显示 fontSizes 的代码。
它应该嵌套在 typography 和 settings 内，如下所示：
{
"settings": {
// Some code...
"typography": {
// Some code...
"fontSizes": [
// Font size definitions here
]
}
}
}
之后，将这些代码行替换为上面的代码片段。只要确保其中没有语法错误即可。
完成后，保存文件并预览您的网站以查看更改。对于 Bluehost 用户，您只需在文件管理器的代码编辑器中单击“保存更改”即可。
如果您想进一步编辑 theme.json，我们强烈建议您更熟悉该文件的结构，如上一节所述。
我们还建议阅读官方 WordPress 设置参考，其中包括可用设置属性的完整列表以及使用它们的说明。
额外提示：使用 WPCode 将自定义代码添加到您的主题
在本指南中，您了解了 theme.json 及其主题定制的潜力。但直接编辑可能还是感觉有点吃力。
幸运的是，还有另一个用户友好的选项来添加自定义代码和进行高级自定义：WPCode。
使用 WPCode，您可以插入自定义代码片段，而无需触摸主题文件本身。这显着降低了定制过程中破坏网站的风险。
如果您想了解有关此代码片段插件的更多信息，请查看我们完整的 WPCode 评论。
另外，这里还有一些有用的教程，可帮助您开始使用 WPCode：
对初学者有用的 WordPress 代码片段（专家精选）
如何在 WordPress 中为回访者突出显示新帖子
如何在 WordPress 中突出显示文本
如何在 WordPress 中轻松添加框阴影
我们希望本文能帮助您了解 WordPress 中的 theme.json 文件。您可能还想查看我们关于如何编辑 WordPress 网站的初学者指南以及我们专家精选的 WordPress 最佳拖放页面构建器。
如果您喜欢这篇文章，请订阅我们的 WordPress 视频教程 YouTube 频道。您还可以在 Twitter 和 Facebook 上找到我们。