theme.json 的结构解析：开发者速查表

长期以来，WordPress® 主题的逻辑主要存在于 functions.php 中。如果你想添加自定义 Logo、宽对齐或编辑器样式的支持，你会使用 add_theme_support()。这是一种可靠但通常比较混乱的主题配置管理方式。

随着区块主题和全站编辑（FSE）的出现，这一职责发生了转变。现在，theme.json 是现代 WordPress 主题的中枢神经系统。它控制区块编辑器、定义全局样式，并管理内容创建者可用的预设。

这是一个庞大的 JSON 对象，初看之下可能令人望而生畏。然而，一旦理解之后，它就能对客户能够和不能做的事情提供精细的控制，这在传统的 PHP 时代是难以实现的。

以下是该文件结构的解析，以及如何使用它来构建更好、更易维护的主题。

Schema（开发者的最佳助手）

使用 theme.json 最大的障碍之一是记住层级结构。是 typography.fontSizes 还是 typography.fontFamilies？color 应该放在 settings 还是 styles 里面？

最有效的改进工作流程的方法是在文件顶部定义 $schema 属性。

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

这不仅仅是元数据。当使用像 VS Code 这样的现代代码编辑器时，这行代码会启用 IntelliSense。它为有效属性提供自动完成建议，如果键嵌套错误会立即报错。它把文件从一场猜测游戏变成了有文档记录的 API。

Settings（构建护栏）

settings 部分是你定义主题规则的地方。在这里你注册调色板、字体大小和布局约束。

关键在于，这也是你锁定 UI 的地方。对于向客户交付网站的机构和自由职业者来说，theme.json 是防止"设计漂移"最有效的方式。通过明确禁用自定义选择器，你可以确保内容创建者只能使用你定义的品牌颜色和排版。

以下是一个强制执行严格设计系统的配置：

"settings": {
    "color": {
        "custom": false,
        "customGradient": false,
        "palette": [
            {
                "slug": "primary",
                "color": "#2C3E50",
                "name": "Midnight Blue"
            },
            {
                "slug": "secondary",
                "color": "#E74C3C",
                "name": "Alizarin"
            }
        ]
    },
    "typography": {
        "customFontSize": false,
        "fontFamilies": [
            {
                "fontFamily": "Helvetica, Arial, sans-serif",
                "name": "Sans Serif",
                "slug": "sans"
            }
        ],
        "fontSizes": [
            {
                "slug": "normal",
                "size": "1rem",
                "name": "Normal"
            },
            {
                "slug": "large",
                "size": "1.5rem",
                "name": "Large"
            }
        ]
    },
    "layout": {
        "contentSize": "800px",
        "wideSize": "1200px"
    }
}

通过将 custom 和 customFontSize 等属性设置为 false，颜色选择器和自定义输入字段会从 WordPress 编辑器中消失。用户只能使用 palette 和 fontSizes 数组中预定义的选择项。

Styles（无需 CSS 的 CSS）

styles 部分有效地取代了传统的 style.css 来处理全局默认值。当 WordPress 渲染页面时，它会读取这个 JSON 对象并自动生成必要的 CSS 变量和类。

注意： 虽然 theme.json 处理视觉样式，但您的主题仍然必须在根目录中包含 style.css 文件。WordPress 依赖于此文件中的头部注释来识别主题名称、作者和版本。您可以让该文件不包含实际的 CSS 规则，但该文件本身是强制性的，否则主题将不会出现在 WordPress 仪表板中。

此结构模仿 CSS 层叠。您首先定义根级默认值（通常应用于 <body>），然后再处理特定元素。

"styles": {
    "color": {
        "background": "var(--wp--preset--color--primary)",
        "text": "#ffffff"
    },
    "typography": {
        "fontFamily": "var(--wp--preset--font-family--sans)",
        "fontSize": "var(--wp--preset--font-size--normal)",
        "lineHeight": "1.6"
    },
    "elements": {
        "link": {
            "color": {
                "text": "var(--wp--preset--color--secondary)"
            },
            ":hover": {
                "color": {
                    "text": "#ffffff"
                },
                "typography": {
                    "textDecoration": "underline"
                }
            }
        },
        "h1": {
            "typography": {
                "fontSize": "3rem",
                "fontWeight": "700"
            }
        }
    }
}

请注意 CSS 变量（例如 var(--wp--preset--color--primary)）的使用。WordPress 会根据 settings 部分中定义的预设自动生成这些变量。使用这些变量可确保调色板中的十六进制代码更改后，会在整个站点中全局更新。

块级覆盖

主题开发中的一个常见挑战是：为特定块应用不同的样式，而无需编写难以覆盖的高度特定的 CSS 选择器。

theme.json 以分层方式处理这个问题。您可以深入到特定块来覆盖全局默认值。

例如，如果您希望所有按钮都具有特定的边框圆角，或希望代码块使用与正文字体不同的等宽字体家族：

"styles": {
    "blocks": {
        "core/button": {
            "border": {
                "radius": "50px"
            },
            "color": {
                "background": "var(--wp--preset--color--secondary)",
                "text": "#ffffff"
            }
        },
        "core/code": {
            "typography": {
                "fontFamily": "\"Courier New\", Courier, monospace",
                "fontSize": "0.9rem"
            },
            "color": {
                "background": "#f0f0f0",
                "text": "#333333"
            }
        }
    }
}

此方法将样式逻辑封装在一起。按钮块的样式附加在块定义本身上，确保只有当页面上实际存在按钮时才会加载这些样式。