WordPress Theme.json 设置完全指南：从入门到精通

发布于2023年10月31日2026年7月30日作者:XQcms

Theme.json 是 WordPress 主题开发的“中央处理器”，它让开发者能够通过一个配置文件控制整个网站的外观和功能。在经典主题时代，我们需要在 functions.php 中使用 add_theme_support() 逐个开启功能，现在这一切都简化了。

本文将详细拆解 theme.json 中 settings 对象的每个属性，帮助你快速掌握这项现代 WordPress 主题开发的核心技能。无论你是想为客户锁定品牌色，还是想开启完整的排版控制，这里都有答案。

开始之前：理解 theme.json 的基础

在深入每个设置之前，先建立正确的认知框架：

什么是 theme.json？ 它是位于主题根目录的配置文件，WordPress 会读取它并自动生成相应的 CSS 和编辑器选项。你只需要关注“做什么”，CSS 生成的工作交给 WordPress。

优先级体系：WordPress 核心 → 主题 → 子主题 → 用户配置。用户在编辑器中的修改拥有高优先级，这也是主题开发中需要做好“护栏”的原因。

一、appearanceTools：一站式开启设计工具

这是 settings 中“偷懒”的开关。将其设为 true，相当于一次性开启了多个设计选项。

json

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

开启后，以下功能会被集体激活：

边框颜色、圆角、样式、宽度
链接颜色
小高度
粘性定位
区块间距、外边距、内边距
行高

注意：如果你需要精细控制，可以单独设置子属性，而不使用这个快捷开关。

二、border：边框控制

控制区块边框的显示选项。四个子属性相互关联——启用任意一个，其余三个也会自动开启[citation:官方资料]。

json

{
  "settings": {
    "border": {
      "color": true,   // 边框颜色
      "radius": true,  // 圆角
      "style": true,   // 实线、虚线、点线等
      "width": true    // 边框粗细
    }
  }
}

三、color：颜色系统

color 是 settings 中丰富的模块，控制着从背景到链接的所有颜色相关功能。

json

{
  "settings": {
    "color": {
      "background": true,      // 背景色（默认开启）
      "text": true,            // 文字色（默认开启）
      "link": false,           // 链接色（默认关闭）
      "custom": true,          // 自定义颜色（默认开启）
      "customGradient": true,  // 自定义渐变
      "palette": [             // 预设调色板
        {
          "slug": "primary",
          "color": "#2C3E50",
          "name": "深蓝"
        },
        {
          "slug": "secondary", 
          "color": "#E74C3C",
          "name": "红色"
        }
      ]
    }
  }
}

实用场景：当为品牌客户开发时，将 custom 设为 false，用户只能从你的预设调色板中选择，避免“设计走样”。

四、dimensions：尺寸控制

目前主要用于控制区块的小高度[citation:官方资料]。

json

{
  "settings": {
    "dimensions": {
      "minHeight": true
    }
  }
}

启用后，支持该属性的区块（如 Cover、Group）将显示小高度设置选项。

五、layout：布局约束

控制内容的宽度范围，是保证页面视觉一致性的关键。

json

{
  "settings": {
    "layout": {
      "contentSize": "800px",  // 内容区宽度
      "wideSize": "1200px"     // 宽对齐宽度
    }
  }
}

六、lightbox：图片灯箱

WordPress 6.4 引入的新功能，专为核心图片块设计[citation:官方资料]。

json

{
  "settings": {
    "lightbox": {
      "allowEditing": true,  // 允许用户在编辑器调整
      "enabled": false       // 默认关闭，设为 true 开启
    }
  }
}

七、position：定位控制

目前支持粘性定位（sticky），让区块在滚动时固定在视口顶部。

json

{
  "settings": {
    "position": {
      "sticky": true
    }
  }
}

八、shadow：阴影效果

控制预设阴影，可自定义或使用系统预设[citation:官方资料]。

json

{
  "settings": {
    "shadow": {
      "defaultPresets": true,
      "presets": [
        {
          "slug": "small",
          "shadow": "0 2px 8px rgba(0,0,0,0.1)",
          "name": "小阴影"
        }
      ]
    }
  }
}

九、spacing：间距控制

管理区块内外间距和间隙。

json

{
  "settings": {
    "spacing": {
      "blockGap": true,      // 区块间垂直间距
      "margin": false,       // 外边距（默认关闭）
      "padding": false,      // 内边距（默认关闭）
      "units": ["px", "em", "rem", "%"]
    }
  }
}

注意：blockGap 的默认值为 null，需要显式开启[citation:官方资料]。

十、typography：排版控制

控制字体、字号、字重等排版参数。

json

{
  "settings": {
    "typography": {
      "customFontSize": true,
      "lineHeight": false,     // 默认关闭
      "fontWeight": true,
      "fontStyle": true,
      "textDecoration": true,
      "textTransform": true,
      "fontFamilies": [
        {
          "fontFamily": "Inter, sans-serif",
          "name": "Inter",
          "slug": "inter"
        }
      ]
    }
  }
}

十一、useRootPaddingAwareAlignments：根内边距对齐

这个设置与 styles.spacing.padding 配合使用。开启后，区块的对齐会感知根元素的内边距，实现更精准的全宽布局控制[citation:官方资料]。

json

{
  "settings": {
    "useRootPaddingAwareAlignments": true
  }
}

注意：使用此功能时，styles.spacing.padding 必须分别定义 top、right、bottom、left。

总结

设置模块	核心作用	默认状态
appearanceTools	批量开启设计工具	false
border	边框样式控制	全部 false
color	颜色系统（背景、文字、调色板）	大部分 true
dimensions	小高度	false
layout	内容宽度约束	–
lightbox	图片灯箱	enabled: false
position	粘性定位	false
shadow	阴影预设	预设开启
spacing	间距（边距、填充）	部分关闭
typography	排版控制	部分开启
useRootPaddingAwareAlignments	根内边距感知	false

掌握这些设置后，你就拥有了用 theme.json 控制 WordPress 主题全局配置的能力。建议从 appearanceTools 和 color.palette 开始实践，逐步探索其他模块。