WordPress主题JSON阴影设置完全指南

发布于2023年9月22日2026年7月30日作者:XQcms

在WordPress主题开发中，theme.json文件扮演着越来越重要的角色。从WordPress 6.3开始，开发者可以通过这个文件为网站添加自定义阴影效果，让设计更加精致。但阴影设置这个功能，说实话有点绕——它同时涉及CSS的box-shadow属性、主题预设管理、用户界面控制等多个层面。很多开发者容易在这里犯错，要么把阴影设置搞混，要么不知道如何正确禁用默认阴影。

这篇文章会带你理清楚WordPress阴影设置的所有细节。我们会从基础的shadow属性说起，解释它和CSS阴影的关系，然后深入探讨如何禁用WordPress自带的阴影预设，以及如何注册你自己的自定义阴影。文中所有示例都来自真实主题开发场景，你可以直接复制使用。

更重要的是，你会明白这些设置如何在后台编辑器中呈现，以及它们生成的CSS变量是如何工作的。这对于控制主题的视觉效果、统一设计语言都很有帮助。

什么是theme.json中的阴影设置

简单来说，settings.shadow是theme.json文件里的一个配置项，专门用来管理WordPress区块的阴影效果。它对应的是CSS的box-shadow属性——注意，这里的阴影特指盒子阴影，和文字阴影（text-shadow）是两码事。

你在theme.json中配置的阴影，终会在两个地方体现：

生成CSS自定义属性（也就是CSS变量），方便你在样式表中调用
在区块编辑器的界面中提供选项，让用户选择

阴影设置的结构

在theme.json文件中，阴影配置的结构是这样的：

json

{
	"version": 2,
	"settings": {
		"shadow": {
			"defaultPresets": true,
			"presets": [
				// 阴影预设数组
			]
		}
	}
}

settings.shadow下有两个配置项：

defaultPresets：布尔值，控制是否启用WordPress自带的默认阴影预设，默认是true
presets：数组，用来注册你自定义的阴影

WordPress的默认阴影预设

WordPress自带了一套阴影预设，这些预设会默认启用。它们分别是：

Natural（自然）：6px 6px 9px rgba(0, 0, 0, 0.2)
Deep（深邃）：12px 12px 50px rgba(0, 0, 0, 0.4)
Sharp（锐利）：6px 6px 0px rgba(0, 0, 0, 0.2)
Outlined（轮廓）：6px 6px 0px -3px rgba(255, 255, 255, 1), 6px 6px rgba(0, 0, 0, 1)
Crisp（清晰）：6px 6px 0px rgba(0, 0, 0, 1)

每个预设都会生成对应的CSS变量，命名规则是--wp--preset--shadow--{slug}。比如Natural的变量就是--wp--preset--shadow--natural。

这些变量会被添加到body选择器中：

css

body {
	--wp--preset--shadow--natural: 6px 6px 9px rgba(0, 0, 0, 0.2);
	--wp--preset--shadow--deep: 12px 12px 50px rgba(0, 0, 0, 0.4);
	--wp--preset--shadow--sharp: 6px 6px 0px rgba(0, 0, 0, 0.2);
	--wp--preset--shadow--outlined: 6px 6px 0px -3px rgba(255, 255, 255, 1), 6px 6px rgba(0, 0, 0, 1);
	--wp--preset--shadow--crisp: 6px 6px 0px rgba(0, 0, 0, 1);
}

为什么要禁用默认阴影

默认阴影预设虽然方便，但并不适合所有主题。它们的设计前提是背景色为白色或浅灰色——如果你的主题使用了深色背景或特殊配色，这些阴影就会显得很突兀。

禁用默认阴影的原因还有：

你希望用户只能使用你精心设计的自定义阴影
你根本不需要阴影效果，想保持界面干净
默认阴影的设计风格和你的主题不搭

如何禁用默认阴影

禁用默认阴影很简单，把defaultPresets设为false就行：

json

{
	"version": 2,
	"settings": {
		"shadow": {
			"defaultPresets": false
		}
	}
}

这样WordPress自带的五个阴影预设就不会加载了。

添加自定义阴影预设

自定义阴影才是真正发挥创造力的地方。通过presets数组，你可以注册任意数量的阴影效果。

每个阴影对象需要三个字段：

name：显示给用户看的名称，支持多语言翻译
slug：机器识别的标识符，用来生成CSS变量名
shadow：合法的CSS box-shadow值

下面是一组来自实际主题的自定义阴影示例：

json

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"shadow": {
			"presets": [
				{
					"name": "小型",
					"slug": "sm",
					"shadow": "0 2px 4px 0 rgba(0, 0, 0, 0.06)"
				},
				{
					"name": "中型",
					"slug": "md",
					"shadow": "0 3px 6px 0 rgba(0, 0, 0, 0.08), 0 2px 4px -2px rgba(0, 0, 0, 0.06)"
				},
				{
					"name": "大型",
					"slug": "lg",
					"shadow": "0 8px 12px -2px rgba(0, 0, 0, 0.1), 0 3px 6px -3px rgba(0, 0, 0, 0.08)"
				},
				{
					"name": "超大",
					"slug": "xl",
					"shadow": "0 16px 24px -4px rgba(0, 0, 0, 0.12), 0 6px 8px -4px rgba(0, 0, 0, 0.08)"
				},
				{
					"name": "内阴影",
					"slug": "inner",
					"shadow": "inset 0 2px 6px 0 rgba(0, 0, 0, 0.06)"
				}
			]
		}
	}
}

每个自定义阴影同样会生成CSS变量，比如上面示例中的--wp--preset--shadow--sm。

阴影在编辑器中的使用位置

目前，WordPress默认只在按钮（Button）区块的界面中显示阴影选项。用户可以通过以下路径找到它：

外观 → 编辑器 → 样式 → 样式手册，然后在样式手册中选择按钮区块，在效果（Effects）选项卡下就能看到阴影选项。

需要注意的是，三方开发的区块也可以利用这些阴影预设，在自己的区块设置面板中添加阴影选择器。

在样式表中使用阴影变量

注册好的阴影预设可以在你的样式表中通过CSS变量来使用。比如：

css

.my-custom-button {
	box-shadow: var(--wp--preset--shadow--md);
}

.featured-card:hover {
	box-shadow: var(--wp--preset--shadow--lg);
}

常见问题解答

问：阴影设置只在按钮区块中生效吗？
目前WordPress核心只在按钮区块中集成了阴影选择器，但其他区块也可以通过开发者的自定义代码来支持阴影选择。

问：自定义阴影能覆盖默认阴影吗？
不能直接覆盖，但你可以禁用默认阴影后再注册同名的自定义阴影。

问：defaultPresets和presets可以同时使用吗？
可以。defaultPresets: true表示启用默认阴影，同时你注册的自定义阴影也会追加到预设列表中。

总结

settings.shadow控制WordPress的box-shadow相关功能
defaultPresets控制是否启用自带的五个阴影预设
presets数组用于注册自定义阴影，每个阴影需要name、slug、shadow三个字段
阴影预设会生成--wp--preset--shadow--{slug}格式的CSS变量
目前核心区块中只有按钮区块内置了阴影选择器
设置defaultPresets: false可以完全移除默认阴影，让主题的视觉效果更统一

掌握theme.json中的阴影设置，相当于拥有了一套系统化的阴影管理方案。它让阴影效果像调色板、字体大小一样，成为设计体系的一部分，而不再是零散的CSS代码片段。