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

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

在这个教程中，我们将探讨theme.json文件的作用，包括它与完整网站编辑的关系。到最后，无论你的开发能力如何，你都会明白如何利用它的功能来创建现代化、高性能的网站。

介绍 theme.json 文件

theme.json文件的核心是一个配置文件，它定义了 WordPress 主题的设置和样式。它使用 JavaScript Object Notation (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 技能在这里将大有裨益。
• WordPress 区块编辑器知识：了解区块是如何工作的，以及它们的自定义选项，将对您的构建工作有所帮助。

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

最后，我们向您推荐几项技术 “附加功能”：

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

有了这些工具和知识，您就可以开始使用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
    }
}

设置和样式对象很简单，但版本需要更多解释。这个值将是一个整数，与你用来读取文件的 API 版本相匹配。当前的 API 版本是3，尽管2版本也很常见，但你可以从旧版本迁移过来。

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

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

从这里开始，你将在设置和样式中添加各种属性和对象，以构建你的文件。

层次结构

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

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

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

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

区块语法

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

这是因为区块主题不是使用 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 -->

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

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

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

如何将 theme.json 和 WordPress 全站编辑结合起来

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

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

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

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

使用 theme.json 文件属性

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

设置

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>标签相关。对于特定元素，可以采用与区块类似的结构，这次使用的是元素属性：

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

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

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

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

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

样式变化

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

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

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

自定义模板和模板部件

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

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

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

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

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

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

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

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

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

模式

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

定义数组的方法很简单：使用patterns属性和库 URL 中相关模式的标题：

有了这个标题，我们就可以填充模式标记了：

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

您就可以在区块编辑器模式目录中选择它们：

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

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

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

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

"$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"
…

接下来，您可以使用定义的 slugs 创建自定义 CSS 属性。例如，您可能创建了自定义字体权重：

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

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

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

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

…
"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文件中。这也是注册任何你想使用的区块模式的时候，如果有必要，还可以创建它们。

您应该使用主题.json 还是 WordPress 全站编辑？

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

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

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

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

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

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

总结

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

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