wordpres核心概念：settings 是干什么的？

发布于 作者:

WordPress主题开发中，theme.json 是一个集中管理全局样式、编辑器设置和设计规范的配置文件。它的 settings 部分相当于主题的“控制面板”——你可以在这里启用或禁用编辑器中的各种设计工具、注册颜色调色板、定义字体大小、配置布局宽度等。过去这些工作分散在 functions.php、CSS 文件和编辑器配置中，现在都统一在 theme.json 的 settings 节点下完成。本文将围绕官方文档中 settings 的各个属性逐一讲解，用通俗的语言和实际代码示例，帮你理解每个配置项的作用和用法。

settings 是 theme.json 的属性之一，主要做两件事：

  1. 控制编辑器里显示哪些设计工具——比如是否允许用户调整边距、是否启用行高控制、是否显示圆角选项。
  2. 注册预设值——比如定义一套品牌色、预设字体大小、间距单位等，这些预设会生成 CSS 变量，供整个主题使用。

简单来说，settings 定义了“用户可以做什么”和“用户可以用什么”。

下面是一个典型的 settings 结构：

json

{
	"version": 2,
	"settings": {
		"appearanceTools": false,
		"border": {},
		"color": {},
		"custom": {},
		"dimensions": {},
		"layout": {},
		"position": {},
		"shadow": {},
		"spacing": {},
		"typography": {},
		"useRootPaddingAwareAlignments": false,
		"blocks": {}
	}
}

逐个来看每个属性的作用。

appearanceTools：一键开启常用工具

appearanceTools 是一个快捷开关，设为 true 时会一次性开启多个常用的设计工具。包括：

  • 边框颜色、圆角、样式、宽度
  • 链接颜色
  • 边距、内边距、区块间距
  • 行高

如果没有这个开关，你需要逐个将上述属性设为 true，代码量会大很多。

注意：appearanceTools 开启后，你仍然可以单独关闭其中某个功能，只需要在对应属性中设为 false 即可覆盖。

border：边框相关设置

控制边框相关的功能开关：

属性说明
border.color是否允许用户自定义边框颜色
border.radius是否允许设置圆角
border.style是否允许选择边框样式（实线、虚线等）
border.width是否允许调整边框粗细

这些开关默认均为 false。如果需要边框功能，记得显式开启。

color：颜色与调色板

color 是 settings 中常用的部分之一，主要做两件事：注册颜色预设，控制颜色相关功能的开关。

注册调色板

json

"color": {
	"palette": [
		{
			"slug": "primary",
			"color": "#0073aa",
			"name": "主色"
		},
		{
			"slug": "secondary",
			"color": "#005a87",
			"name": "辅色"
		}
	]
}

注册后，WordPress 会自动生成 CSS 变量，比如 --wp--preset--color--primary，你可以在样式或 CSS 中直接引用它。

常用控制开关

属性说明
color.custom是否允许用户选择自定义颜色（非预设颜色）
color.link是否允许设置链接颜色
color.heading是否允许设置标题颜色
color.button是否允许设置按钮颜色
color.caption是否允许设置图片标题颜色
color.gradients是否启用渐变预设
color.duotone是否启用双色调滤镜

注意：color.text 和 color.background 默认是开启的。

custom：自定义 CSS 变量

custom 属性允许你定义自己的 CSS 变量，这些变量会像预设变量一样被输出到页面中。

json

"custom": {
	"spacing": {
		"unit": "2rem"
	}
}

这会生成 --wp--custom--spacing--unit: 2rem 这样的变量。适合存放主题特有的设计数值。

dimensions：尺寸控制

主要用于控制区块的小高度等尺寸相关功能。

属性说明
dimensions.minHeight是否允许用户设置区块的小高度

其他如 aspectRatio（宽高比）、width、height 等功能在 WordPress 6.6 及以后版本陆续得到支持。

layout：布局宽度设置

layout 用于定义内容区域和宽屏内容的宽度限制：

json

"layout": {
	"contentSize": "640px",
	"wideSize": "1200px"
}
  • contentSize：普通内容的大宽度。
  • wideSize：使用 .alignwide 类时的大宽度。

这两个值会影响编辑器中对齐选项的行为，也是实现“全宽/宽屏”布局的基础。

lightbox：图片灯箱

lightbox 控制图片灯箱功能：

属性说明
lightbox.enabled是否启用灯箱
lightbox.allowEditing是否允许用户在编辑器中修改灯箱设置

如果设为 false，用户将无法在编辑器里调整灯箱相关选项。

position：定位支持

目前主要支持 sticky（粘性定位）：

属性说明
position.sticky是否允许区块使用粘性定位

启用后，用户在编辑器中可以为支持的区块开启“粘性”效果。

shadow：阴影预设

注册自定义阴影预设，并控制用户能否使用阴影功能：

json

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

defaultPresets 控制是否使用 WordPress 默认的阴影预设。

spacing：间距控制

控制边距、内边距和区块间距：

属性说明
spacing.margin是否允许设置外边距
spacing.padding是否允许设置内边距
spacing.blockGap是否启用区块间的间距控制
spacing.units允许使用的单位列表，如 ["px", "em", "rem", "%"]

默认情况下，margin 和 padding 是关闭的，需要显式开启。

typography：排版控制

排版是主题设计的核心，typography 提供了丰富的控制选项。

注册字体大小

json

"typography": {
	"fontSizes": [
		{
			"slug": "small",
			"size": "0.875rem",
			"name": "小"
		},
		{
			"slug": "normal",
			"size": "1rem",
			"name": "正常"
		},
		{
			"slug": "large",
			"size": "1.5rem",
			"name": "大"
		}
	]
}

每个预设会生成 --wp--preset--font-size--small 这样的 CSS 变量。

注册字体家族

json

"typography": {
	"fontFamilies": [
		{
			"slug": "sans",
			"fontFamily": "Inter, system-ui, sans-serif",
			"name": "无衬线体"
		}
	]
}

生成的变量为 --wp--preset--font-family--sans。

常用控制开关

属性说明
typography.customFontSize是否允许用户自定义字体大小
typography.lineHeight是否允许设置行高
typography.letterSpacing是否允许设置字间距
typography.fontWeight是否允许设置字重
typography.textDecoration是否允许设置文本装饰（下划线、删除线等）
typography.textTransform是否允许设置大小写转换

这些开关默认大多为 false。

useRootPaddingAwareAlignments：根内边距感知对齐

这是一个特殊的布尔值开关。设为 true 时，相当于同时开启了 spacing.margin 和 spacing.padding。更关键的是，它让全宽区块能够“感知”根元素的内边距——即全宽区块的内容会遵循根内边距的约束，而区块本身可以延伸至边缘。

简单理解：它让全宽布局更优雅，不会让内容紧贴屏幕边缘。

blocks：按块覆盖设置

blocks 允许你针对特定区块单独配置 settings，覆盖全局设定。例如：

json

"blocks": {
	"core/button": {
		"color": {
			"palette": [
				{
					"slug": "btn-primary",
					"color": "#0073aa",
					"name": "按钮主色"
				}
			]
		},
		"border": {
			"radius": true
		}
	}
}

这里为按钮区块单独注册了颜色调色板，并开启了圆角功能，而不影响其他区块。

总结

settings 是 theme.json 中核心的部分之一，它通过一套统一的配置体系，替代了过去分散在多个文件中的主题设置。理解它，就能更好地控制 WordPress 主题的设计自由度——既可以为用户提供丰富的工具，也可以严格限制设计选项，保持品牌一致性。

记住几个关键点：

  1. appearanceTools 是快速开启常用功能的捷径。
  2. 预设值（调色板、字体大小等）会自动生成 CSS 变量，方便在样式中复用。
  3. 每个功能默认大多是关闭的，需要显式开启。
  4. blocks 可以针对特定区块做精细化控制。