WordPress主题的theme.json文件完全指南

发布于 作者:

如果你正在开发WordPress主题，特别是块主题（Block Theme），那么theme.json就是你需要掌握的核心文件。它就像一个中央控制台，统一管理主题的全局设置、样式配置、功能开关等一切。无论你构建的是经典主题还是块主题，这个文件都能让主题开发更加规范和。通过theme.json，你可以启用或禁用各种编辑器功能（如色彩控制、间距调整、排版选项），自定义颜色方案和字体，甚至直接定义网站的整体样式体系。更关键的是，该文件采用标准化的JSON格式，让WordPress核心、主题本身、插件和用户之间能够”说同一种语言”——你在theme.json中的每一项配置，都会自动反映在网站前台和管理后台的编辑器中。对于块主题而言，theme.json的重要性甚至超越了functions.php，成为整个主题的”地基”。下面，我们从基础的结构开始，逐步深入到各个配置项的具体用法。

认识theme.json的基本结构

一个标准的theme.json文件，其顶层结构通常包含以下几个核心部分：

json

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 2,
    "settings": {},
    "styles": {},
    "customTemplates": {},
    "templateParts": {},
    "patterns": []
}
  • $schema：这是一个可选的属性，指向JSON Schema的URL地址。加入它之后，许多现代代码编辑器（如VS Code）会自动提供代码提示和错误检查，大提升开发体验。
  • version：这是必填属性，用于告诉WordPress你使用的API版本。目前（截至2026年）新的稳定版本是2。如果不设置此属性，WordPress会默认按版本1来解析你的配置，可能导致一些新特性无法生效。
  • settings：用于控制编辑器界面中哪些功能选项对用户可见（如色彩面板、字体大小控制器），同时也可以定义预设值（如调色板、渐变方案）。
  • styles：为网站整体和各个区块（Block）定义具体的样式值，如背景色、文字颜色、间距等。这些样式会直接输出到前端页面和管理后台的编辑器中。
  • customTemplates：注册自定义模板（如”全宽页面”、”无侧边栏文章”），让用户可以在站点编辑器中选用。
  • templateParts：注册可复用的模板部件（如”页头”、”页脚”），方便在模板中重复引用。
  • patterns：一个数组，用于从官方Pattern Directory中引入区块模式（Pattern）到你的主题中。

版本管理：为什么要始终设置version

在theme.json中，version属性必须始终存在。它不仅仅是一个数字，更是保证你的主题在未来WordPress版本中正常工作的”契约”。目前API版本为2，在可预见的未来，这个版本号会随着新功能引入而递增。

json

{
    "version": 2
}

这个其简洁的代码块，实际上就是theme.json的”小可行结构”。即使你暂时不配置任何样式或设置，仅仅加上version: 2，你的主题就已经迈出了标准化的一步。

JSON Schema：开发者的得力助手

虽然$schema属性是可选的，但在实际开发中，它的价值无可替代。将这个URL添加到文件中后，你的编辑器就能”读懂”整个theme.json的数据结构，在你输入每个属性时，自动补全可用的选项，并标记出拼写错误或类型不匹配的地方。

json

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

很多初学者在刚开始手写theme.json时，经常会因为缺少一个花括号或多了一个逗号而导致整个文件失效。添加Schema后，编辑器会实时高亮这些语法问题，让你能像编写常规代码一样顺畅地构建配置文件。

深入settings：打开或关闭功能开关

settings是整个文件中较为复杂的部分之一。它控制着WordPress编辑器中哪些功能面板会出现在用户界面上，同时也能定义预设值供用户选择。

控制功能可见性

通过settings，你可以全局或针对特定区块，决定是否启用某些控制选项。例如：

json

{
    "version": 2,
    "settings": {
        "color": {
            "custom": true,
            "palette": [
                {
                    "slug": "foreground",
                    "color": "#000000",
                    "name": "默认黑"
                },
                {
                    "slug": "background",
                    "color": "#ffffff",
                    "name": "默认白"
                }
            ]
        },
        "typography": {
            "fontSizes": [
                {
                    "slug": "small",
                    "size": "13px",
                    "name": "小"
                },
                {
                    "slug": "medium",
                    "size": "20px",
                    "name": "中"
                },
                {
                    "slug": "large",
                    "size": "36px",
                    "name": "大"
                }
            ]
        },
        "spacing": {
            "margin": true,
            "padding": true,
            "blockGap": true
        }
    }
}

上面的示例中，我们：

  • 定义了自定义色板（palette），让用户在插入区块时可以直接选用主题预设的色彩。
  • 设置了字体大小选项，指定了”小”、”中”、”大”三档尺寸。
  • 开启了间距控制（spacing），让用户可以调节区块的外边距（margin）和内边距（padding）。

针对特定区块的配置

你还可以为某个特定区块单独设置选项。例如，只对”段落”区块关闭掉自定义颜色的功能，而其他区块保持不变：

json

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

这里core/paragraph是段落区块的内部名称，所有WordPress核心区块都有一个类似的命名空间，格式为core/区块名。

应用styles：定义视觉样式

如果说settings是”功能开关区”，那么styles就是”具体样式值区”。在这里，你可以直接定义颜色、字体、间距、边框等CSS属性，它们会自动应用到前台和后台。

json

{
    "version": 2,
    "styles": {
        "color": {
            "background": "#f0f0f0",
            "text": "#222222"
        },
        "typography": {
            "fontFamily": "var(--wp--preset--font-family--body)",
            "fontSize": "var(--wp--preset--font-size--medium)"
        },
        "spacing": {
            "padding": {
                "top": "2rem",
                "bottom": "2rem"
            }
        }
    }
}

上面的配置为整个网站设置了浅灰色背景、深灰色文本，并应用了主题预定义的字体和字号。所有区块在默认情况下会继承这些样式，除非你在blocks属性中为特定区块覆盖这些值。

针对区块的样式覆盖

与settings类似，你可以在styles中单独为某个区块指定样式：

json

{
    "version": 2,
    "styles": {
        "blocks": {
            "core/heading": {
                "color": {
                    "text": "#1a1a1a"
                },
                "typography": {
                    "fontFamily": "var(--wp--preset--font-family--heading)"
                }
            }
        }
    }
}

这样，所有标题（Heading）区块就会使用专门的标题字体和颜色，而网站其他部分保持不变。

自定义模板与模板部件

customTemplates和templateParts这两个属性主要服务于块主题的模板系统。

注册自定义模板

假设你在主题的/templates文件夹中创建了一个full-width.html文件，想让用户在站点编辑器的”模板”面板中看到并选用它，就可以这样注册：

json

{
    "version": 2,
    "customTemplates": [
        {
            "name": "full-width",
            "title": "全宽页面",
            "postTypes": [ "page" ]
        }
    ]
}
  • name对应模板文件的名称（不含.html后缀）。
  • title是显示在用户界面中的名称。
  • postTypes指定该模板适用于哪些内容类型（如页面、文章、自定义文章类型）。

注册模板部件

对于/parts文件夹中的可复用部件（如header.html、footer.html），可以这样注册：

json

{
    "version": 2,
    "templateParts": [
        {
            "name": "header",
            "title": "页头",
            "area": "header"
        },
        {
            "name": "footer",
            "title": "页脚",
            "area": "footer"
        }
    ]
}

area字段用于指定该部件所属的区域，常见的值有header、footer和uncategorized，这有助于WordPress在站点编辑器中正确组织和显示它们。

引入区块模式

WordPress官方维护着一个庞大的区块模式（Pattern）目录，你可以在自己的主题中直接引入这些模式，而不需要手动复制代码。patterns属性就是为此而设计的：

json

{
    "version": 2,
    "patterns": [
        "core/social-links",
        "core/query-grid"
    ]
}

这里的core/social-links和core/query-grid是来自Pattern Directory的模式标识符。引入后，用户在插入区块时就能在”模式”选项卡中找到它们。

总结

theme.json的出现，彻底改变了WordPress主题的开发方式。它让原本需要大量PHP代码和CSS编写才能实现的功能，变成一个结构化的JSON文件就能解决。回顾一下核心要点：

  • version始终设为新，这是保证你的theme.json被正确解析的基础。
  • 善用$schema，可以在编辑器中获得实时代码提示，大幅减少低级的语法错误。
  • settings控制”能不能用”，管理编辑器功能面板的显示与隐藏，以及预设值的定义。
  • styles控制”长什么样”，为网站整体和特定区块定义具体的CSS样式值。
  • customTemplates和templateParts让块主题的模板系统更加灵活，可以按需注册自定义布局。
  • patterns则让你能轻松复用社区中的优秀设计。

对于初学者而言，有效的学习方式是从一个小化的theme.json开始，逐步添加你需要的配置项。WordPress官方文档和社区中有大量的现成示例，对照着你的实际设计需求，慢慢摸索和实验，你会发现这个”中央配置文件”比你想象中更加直观和强大。