theme.json 完全指南：WordPress 主题全局设置与样式

发布于 作者:

对于任何一个想认真做 WordPress 主题开发的人来说，theme.json 都是绕不开的核心文件。它不是一个硬性要求的文件，但如果你想让自己的主题跟上 WordPress 的发展节奏，几乎每个项目都得跟它打交道。

简单来说，它就是主题的“总控台”。以往你要在 functions.php 里写一堆代码来开启或关闭编辑器的某些功能，要在 style.css 里定义全局颜色变量，还得为不同区块单独写样式——现在，所有这些都可以在一个 theme.json 文件里集中搞定。从控制后台编辑器能显示哪些颜色选项，到定义网站全局的默认字体和间距，再到给不同的区块（比如段落、按钮、封面图）预设好样式，theme.json 都能派上用场。用好它，你的主题代码会更干净，维护起来也更省心。

认识 theme.json：它到底是什么？

theme.json 本质上是一个位于你主题根目录下的配置文件。它使用 JSON 格式来组织数据，把主题的设置（Settings）和样式（Styles）统一管理起来。

在它出现之前，主题开发者得用好几个文件才能达到同样的效果。比如，在 functions.php 里用 add_theme_support 开启功能，在 CSS 文件里定义变量和样式。theme.json 的出现把这套流程标准化了。它提供了一个“通用语言”，让 WordPress 核心、主题、插件和用户之间能通过统一的方式沟通。你在后台“外观 > 编辑器”里做的任何样式调整，终都会反映到这个文件的配置逻辑里 。

为什么推荐你用 theme.json？

  • 集中管理：所有跟样式、设置相关的配置都在一个文件里，不用再四处翻找。
  • 减少 CSS 代码量：很多基础的样式（比如颜色、间距、排版）都可以在 theme.json 里定义，WordPress 会自动生成对应的 CSS，你不再需要写大量的样板式代码 。
  • 更精细的控制：你可以精确到为某个特定的区块（比如“新文章”区块）单独开关某些功能或设定默认样式。
  • 面向未来：这是 WordPress 全站编辑（FSE）的基石，也是未来主题开发的主流方向。

当然，这并不意味着你要彻底扔掉 CSS。复杂的动画、过渡效果或某些特殊布局，还是需要额外 CSS 来配合的 。

theme.json 的核心结构

一个基本的 theme.json 文件至少需要包含 version 和两个核心的节点：settings 和 styles。

打开你主题根目录下的 theme.json 文件（如果没有，可以创建一个），它的骨架大概是这样：

json

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 2,
    "settings": {
        // 全局设置写在这里
    },
    "styles": {
        // 全局样式写在这里
    }
}

注意：$schema 这行不是必须的，但强烈建议加上。它能让你在代码编辑器（比如 VSCode）里获得自动补全和语法提示，写起来不容易出错，效率也高很多 。

我们挨个解释一下这几个关键部分。

设置（Settings）：控制“能做什么”

settings 节点是用来定义后台编辑器的“能力范围”的。简单说，就是你想让用户看到哪些控件、能调整哪些东西。

举个例子，如果你想简化用户的选择，只让用户使用主题预定义的几种颜色，不允许他们使用“自定义颜色”或者“自定义渐变色”，可以这样设置：

json

{
    "version": 2,
    "settings": {
        "color": {
            "custom": false,
            "customGradient": false,
            "palette": [
                {
                    "slug": "primary",
                    "color": "#007cba",
                    "name": "主色"
                },
                {
                    "slug": "secondary",
                    "color": "#6c8ba0",
                    "name": "辅色"
                }
            ]
        }
    }
}

上面的代码做了几件事：

  1. 把 custom 和 customGradient 设为 false，用户就没法在编辑器里自由选色或创建渐变。
  2. 定义了一个调色板（palette），用户只能在“主色”和“辅色”这两个颜色里选。

类似的玩法还有很多。比如，你还可以通过 appearanceTools 这个“快捷开关”一次性开启或关闭边框、间距、行高等一系列功能 ：

json

{
    "version": 2,
    "settings": {
        "appearanceTools": true
    }
}

把它设为 true，用户就能直接在图块设置里调整边框、内边距、外边距和行高了，非常方便 。

除了全局设置，你还能针对特定区块（blocks）来做控制。比如，你想让“按钮”区块可以使用自定义颜色，但其他区块不行，就可以这样写：

json

{
    "version": 2,
    "settings": {
        "blocks": {
            "core/button": {
                "color": {
                    "custom": true
                }
            }
        }
    }
}

这样一来，只有编辑按钮时，自定义颜色的选项才会出现 。

注意，settings 里定义的很多配置，比如颜色 palette 或字体大小 fontSizes，会自动生成 CSS 自定义属性（变量），你可以直接在样式中引用它们。

样式（Styles）：定义“长什么样”

有了 settings 定义了规则，styles 就是用来实际应用这些规则，决定网站前端终长什么样的。

全局样式（Global Styles）定义在 styles 的根节点下，会影响到整个网站。比如，你想让网站的背景色用你自定义调色板里的“主色”，文本颜色用“辅色”：

json

{
    "version": 2,
    "styles": {
        "color": {
            "background": "var(--wp--preset--color--primary)",
            "text": "var(--wp--preset--color--secondary)"
        },
        "typography": {
            "fontSize": "18px"
        }
    }
}

这里用到的 var(--wp--preset--color--primary) 就是 WordPress 根据你在 settings 中定义的调色板自动生成的 CSS 变量。--primary 对应的是你在 palette 里定义的 slug 值 。

和 settings 类似，样式也可以精确到某个区块（blocks）或元素（elements）。

比如，你只想让“文章内容”区块里的文字用“主色”，可以这样做：

json

{
    "version": 2,
    "styles": {
        "blocks": {
            "core/post-content": {
                "color": {
                    "text": "var(--wp--preset--color--primary)"
                }
            }
        }
    }
}

或者你想让全站所有的链接都变成“辅色”，可以设置 elements：

json

{
    "version": 2,
    "styles": {
        "elements": {
            "link": {
                "color": {
                    "text": "var(--wp--preset--color--secondary)"
                }
            }
        }
    }
}

理解优先级：谁说了算？

theme.json 的配置是会“继承”和“覆盖”的。理解这个层级关系很重要，能帮你避免明明写了样式却不生效的困惑。

优先级从低到高大致是 ：

  1. WordPress 默认值：如果主题什么都没定义，就使用 WordPress 核心提供的默认样式。
  2. 父主题的 theme.json（如果你在用子主题的话）。
  3. 子主题的 theme.json：子主题里的配置会覆盖父主题的。
  4. 用户通过站点编辑器（Site Editor）做的修改：用户在后台上手调整的样式，拥有高的优先级。

所以，theme.json 更像是主题开发者设定的“默认值”或“基线”，用户终有权利在上面进行个性化的调整，而且这些调整会保存下来，不会被主题更新覆盖掉 。

从 functions.php 到 theme.json 的迁移

如果你之前做过经典主题开发，可能会习惯在 functions.php 里用 add_theme_support 来开启功能。现在，这些操作正逐步迁移到 theme.json 中。

举个例子，在经典主题里，你要禁用自定义颜色，会这么写：

php

add_theme_support( 'disable-custom-colors' );

在 theme.json 里，等效的做法是 ：

json

{
    "version": 2,
    "settings": {
        "color": {
            "custom": false
        }
    }
}

目前，WordPress 仍然会支持 functions.php 里的旧写法以保持兼容，但 theme.json 是大势所趋，建议新主题都尽量通过它来配置。

总结

theme.json 为 WordPress 主题开发带来了一种全新的、更标准化的方式。它把散落在各处的配置集中到一个文件里，让主题开发者能用结构化的数据，去精确地控制编辑器功能和网站的全局样式。

  • 集中配置：用 settings 控制“能做什么”，用 styles 控制“长什么样”。
  • 精细控制：设置和样式都可以作用于全局、特定区块或特定元素。
  • 代码更少：WordPress 会根据你的配置自动生成大量 CSS 和 CSS 变量，减少了你手写样式的工作量 。
  • 面向未来：它是全站编辑体验的基石，掌握它意味着你正走在 WordPress 主题开发的前沿。

对于初学者来说，从模仿现成主题（比如默认的 Twenty Twenty-Four 主题）的 theme.json 文件开始，是上手的好办法 。多用代码编辑器的自动补全功能，很快你就能掌握其中的门道。