什么是 WordPress 的 theme.json 文件及其用法

最后更新于 2024 年 6 月 10 日 | 编辑部撰写 | 审核人：Syed Balkhi

你是否在使用区块主题并在 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 规则来对这些功能进行样式化。在区块主题中，theme.json 作为一个集中的枢纽，定义了区块主题的所有外观和感觉。它可以让你在一个地方定义诸如字体、颜色和布局选项，取代了在 functions.php 文件中使用 add_theme_support() 的需求。

这也是为什么区块主题中的 functions.php 文件通常比经典主题中的小得多。拥有一个专门的 theme.json 文件能带来一些前经典主题系统无法实现的好处。首先，theme.json 与 WordPress 全站编辑器紧密合作，使你可以在编辑器内直接定制主题的样式和设置，无需碰触任何代码。此外，theme.json 旨在为开发者和用户创造一致的体验。一些用户会觉得更换主题时需要完全学习新的布局和样式选项非常令人沮丧。借助 theme.json，切换主题变得更加流畅，因为一切都是以相似的方式组织的。最后，通过使用 theme.json，主题开发者和用户可以随着 WordPress 不断扩展其全站编辑功能，确保他们的工作具有前瞻性。

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

theme.json 文件位于你主题目录内的 public_html » wp-content » themes » 你的主题名称 » theme.json。不论使用 FTP 还是主机账户的文件管理器访问它，首先需要连接到你的网站。

theme.json 文件看起来是什么样的？

theme.json 文件有一个特定的结构，组织了你 WordPress 区块主题的所有全局设置。根据主题的复杂程度，文件可能很短或很长。然而，这个文件可以被分解为 7 个顶级部分：

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

Schema （Schema 属性是区块主题中可选的，在某些主题中可能看不到。）

Schema 属性链接到 WordPress JSON schema 的 URL，这定义了主题的全局设置、样式和其他配置。

Version

该部分指定 theme.json 格式使用的 API 版本，确保它遵循正确的结构。撰写本文时，API 的版本是 2。

Settings

此属性定义了用户可以用来定制主题的选项和控件，包括颜色调色板、排版、间距、渐变、阴影、边框等的预设。

这是一个简单的示例：

{
"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"
 }
 }
}
}
}

Styles

虽然 settings 部分定义了主题的默认定制选项，styles 部分则将其应用到主题。你可以将定制设置应用于整个网站或在块级别上使用预设。

这是一个示例：

{
"settings": {},
"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"
}
}
}
}

Custom Templates

区块主题开发者可以创建预定义的布局供用户使用。Twenty Twenty-Four 主题在 theme.json 文件中定义了多个自定义模板：Page No Title, Page With Sidebar, Page with wide Image, 和 Single with Sidebar。你可以使用任何这些来创建内容。

示例代码：

{
"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"
 }
]
}

Template Parts

模板部分是可以在自定义模板中使用的可复用区域。这些元素包括页眉、页脚、侧边栏等等。示例代码：

{
"templateParts": [
 {
 "area": "header",
 "name": "header",
 "title": "Header"
 },
 {
 "area": "footer",
 "name": "footer",
 "title": "Footer"
 },
 {
 "area": "sidebar",
 "name": "sidebar",
 "title": "Sidebar"
 },
 {
 "area": "post-meta",
 "name": "post-meta",
 "title": "Post Meta"
 }
]
}

Patterns

模式是预制的块集合，可让你在页面、帖子或任何其他地方创建自定义内容布局。theme.json 允许主题开发者从公共模式目录引用模式，提供更多定制选项而无需自己设计这些可复用的块。示例代码：

{
"patterns": [
 "three-columns-of-services",
 "clients-section"
]
}

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

由于 theme.json 是核心主题文件，在你的在线 WordPress 网站上直接编辑它存在一定的风险。意外错误可能会破坏你的主题或网站。一个更安全的方法是使用子主题。子主题继承父主题的所有样式和功能，但允许你定制而不修改父主题本身。如果父主题接收到更新，你的定制不会被覆盖。

你可以阅读我们关于如何在 WordPress 中创建子主题的指南。该文章展示了一种使用 Create Block Theme 插件的简易方法，该插件会自动生成一个新的 theme.json 文件，仅供子主题使用。为了确保顺利的编辑体验并避免网站停机，我们还建议创建 WordPress 网站的新备份。推荐使用 Duplicator 插件进行快速可靠的备份。还建议在本地 WordPress 开发环境或临时站点工作。这会创建你在线网站的副本，使你可以在不影响访问者的情况下安全测试更改。

如何编辑 WordPress theme.json 文件

无需代码编辑 theme.json（适合初学者）

若不想直接触及代码来编辑 theme.json 文件，可以使用 Create Block Theme 插件。安装这个插件后，在管理界面进入 Appearance » Editor 。然后选择‘样式’，接着点击铅笔‘编辑样式’图标，这会带你到块编辑器编辑网站的全局样式。改变主题样式后，保存更改并进入创建区块主题的按钮‘保存更改到主题’。网站会自动保存你对 theme.json 文件的更改。

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

这方法推荐给有代码经验的用户。首先在主题目录中打开你的 block 主题的 theme.json 文件。使用 FTP 或者主机的文件管理器。在 theme.json 文件的 settings 属性中定义样式，并在 styles 属性中具体实现。例如，创建自定义字体大小：

{
 "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-large",
 "size": "48px"
 }
]
}
}

保存文件后预览网站查看更改。了解更多关于 theme.json 文件的结构请参阅前一部分的详细说明。