WordPress 主题开发：theme.json 中预设与样式的协同运用

用预设值管理主题样式，让设计系统化、维护更轻松

在 WordPress 主题开发中，theme.json 是管理样式与设置的核心配置文件。本文聚焦于一个关键能力：如何将已注册的预设（Presets）作为样式值，应用到主题的各个设计元素中。你将理解预设的本质（即 CSS 自定义属性的标准化接口），掌握 var:preset|feature|slug 引用语法，并学会区分标准预设与自定义预设（var:custom）的使用场景。通过颜色、字体、间距等实例，你将建立起一套可维护、可扩展的主题设计工作流。无论你是刚接触区块主题，还是希望规范现有主题架构，这份指南都能提供切实的参考。

---

预设的本质

预设（Presets）是注册在 settings 下的配置项，它们通常会在编辑器界面中呈现为可选选项（如调色板、字号下拉菜单）。WordPress 会为每个预设自动生成对应的 CSS 自定义属性（Custom Properties），命名规则为 --wp--preset--{feature}--{slug}。

来看一个包含三种颜色的调色板定义：

json

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "color": "#f8f9fa", "name": "背景基础", "slug": "base" },
        { "color": "#212529", "name": "正文对比", "slug": "contrast" },
        { "color": "#4dabf7", "name": "主色调", "slug": "primary" }
      ]
    }
  }
}

WordPress 将生成如下 CSS 变量：

css

body {
  --wp--preset--color--base: #f8f9fa;
  --wp--preset--color--contrast: #212529;
  --wp--preset--color--primary: #4dabf7;
}

预设的本质是一套标准化的、可交互的 CSS 变量生成机制。无论是主题开发者、插件还是用户，都可以通过相同的方式注册和调用这些值。

---

在样式中引用预设

有了预设，下一步就是将其应用到默认样式中。引用预设的专用语法是 var:preset|{feature}|{slug}。

沿用上面的调色板，实现以下设计：

• 全站背景使用 base（浅灰）
• 正文文字使用 contrast（深灰）
• 链接文字使用 primary（亮蓝）

json

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "color": "#f8f9fa", "name": "背景基础", "slug": "base" },
        { "color": "#212529", "name": "正文对比", "slug": "contrast" },
        { "color": "#4dabf7", "name": "主色调", "slug": "primary" }
      ]
    }
  },
  "styles": {
    "color": {
      "text": "var:preset|color|contrast",
      "background": "var:preset|color|base"
    },
    "elements": {
      "link": {
        "color": {
          "text": "var:preset|color|primary"
        }
      }
    }
  }
}

注意：CSS 原生语法 var(--wp--preset--color--contrast) 虽然可行，但 var:preset|... 在后台界面中显示更完整，推荐使用。

---

自定义预设（Custom Presets）

除了标准预设，WordPress 还允许注册“自定义预设”——即非标准化的 CSS 变量，通过 settings.custom 定义。命名规则为 --wp--custom--{key}--{subKey}。

典型场景：需要一套设计系统中使用的行高比例。

json

{
  "version": 2,
  "settings": {
    "custom": {
      "lineHeight": {
        "xs": "1.2",
        "sm": "1.4",
        "md": "1.6",
        "lg": "1.8"
      }
    }
  }
}

生成的 CSS 变量：

css

body {
  --wp--custom--line-height--xs: 1.2;
  --wp--custom--line-height--sm: 1.4;
  --wp--custom--line-height--md: 1.6;
  --wp--custom--line-height--lg: 1.8;
}

在样式中引用时使用 var:custom 前缀：

json

{
  "version": 2,
  "settings": {
    "custom": {
      "lineHeight": {
        "xs": "1.2",
        "sm": "1.4",
        "md": "1.6",
        "lg": "1.8"
      }
    }
  },
  "styles": {
    "typography": {
      "lineHeight": "var:custom|line-height|md"
    }
  }
}

自定义预设适合存储项目独有的设计变量（间距尺度、字重体系、圆角半径等），不依赖 WordPress 原生 UI 控件，完全由主题开发者自主掌控。

---

可注册预设的功能模块

以下功能均支持在 settings 中注册预设，并在 styles 中引用：

功能模块	settings 路径	预设示例
颜色	color.palette	背景色、文字色、链接色
阴影	shadow.presets	卡片阴影、弹窗阴影
间距	spacing.spacingSizes	内边距、外边距的尺度
排版字号	typography.fontSizes	正文字号、标题字号
字体系列	typography.fontFamilies	系统字体、自定义字体
自定义	custom	行高、字重、圆角等

---

总结

theme.json 的预设与样式协同机制，本质是将设计决策集中到一处，并通过标准化语法应用到主题各处。核心要点：

1. 预设是 CSS 自定义属性的生成器，命名遵循 --wp--preset--{feature}--{slug} 规范；
2. 引用预设使用 var:preset|feature|slug，优于直接写 CSS 变量名；
3. 自定义预设通过 settings.custom 定义，引用前缀为 var:custom；
4. 预设可在编辑界面中作为选项呈现，用户可在此基础上自由调整；
5. 将预设与样式分离，使主题设计更具弹性，维护成本大幅降低。

掌握这套机制后，无论是开发深度定制的区块主题，还是构建企业级设计系统，你都将拥有一个清晰、可靠的技术底座。