阴影

最后更新：2026-10-05 15:56:51

theme.json 中的 settings.shadow 属性目前允许您创建自定义阴影预设。从 WordPress 6.3 版本开始，它不再包含启用或禁用 UI 元素的设置。

在此处，“阴影”特指 box-shadow CSS 功能，与 text-shadow 无关。

阴影设置

settings.shadow 属性包含两个您可以配置的设置：

defaultPresets: 用于启用或禁用默认 WordPress 阴影预设的布尔值。默认为 true。
presets: 一个对象数组，用于在主题中或供用户注册自定义阴影。

以下是 theme.json 中默认阴影属性的示例：

{
	"version": 2,
	"settings": {
		"shadow": {
			"defaultPresets": true,
			"presets": [
				{
					"name": "Natural",
					"slug": "natural",
					"shadow": "6px 6px 9px rgba(0, 0, 0, 0.2)"
				},
				{
					"name": "Deep",
					"slug": "deep",
					"shadow": "12px 12px 50px rgba(0, 0, 0, 0.4)"
				},
				{
					"name": "Sharp",
					"slug": "sharp",
					"shadow": "6px 6px 0px rgba(0, 0, 0, 0.2)"
				},
				{
					"name": "Outlined",
					"slug": "outlined",
					"shadow": "6px 6px 0px -3px rgba(255, 255, 255, 1), 6px 6px rgba(0, 0, 0, 1)"
				},
				{
					"name": "Crisp",
					"slug": "crisp",
					"shadow": "6px 6px 0px rgba(0, 0, 0, 1)"
				}
			]
		}
	}
}

如您所见，WordPress 注册了几个默认预设，您可以直接在块样式中使用，或者让用户从界面中选择：

Natural
Deep
Sharp
Outline
Crisp

与所有预设一样，WordPress 将为每个注册的阴影生成一个 CSS 自定义属性。阴影预设命名为 --wp--preset--shadow--{$slug}。

以下是为默认阴影预设生成的 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);
}

禁用核心 WordPress 阴影

核心中可用的默认阴影并不适合每个主题的设计。通常，它们仅适用于背景为白色或非常浅灰色的主题。如果您的主题使用不同的颜色，您几乎总是希望移除这些预设。

但禁用默认值可能有其他原因。也许您只想限制用户使用专门为您的主题设计的阴影，或者只是不喜欢它们的设计。

无论出于何种原因，您可以通过在 theme.json 中将 settings.shadow.defaultPresets 设置为 false 来移除它们：

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

添加自定义阴影预设

WordPress 允许您注册任意数量的自定义阴影。您可以通过 settings.shadow.presets 属性添加它们，这是一个用于存储阴影对象的数组。此数组中的每个对象应包含三个值：

name: 阴影的可读名称或标签，可以翻译。
slug: 阴影的机器可读标识符，用于构建其关联的 CSS 自定义属性。
shadow: box-shadow CSS 属性的有效 CSS 值。

尝试注册几个自己的阴影。您可以使用此 theme.json 代码开始，其中包含几个阴影示例：

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"shadow": {
			"presets": [
				{
					"name": "Small",
					"slug": "sm",
					"shadow": "0 1px 2px 0 rgb(0 0 0 / 0.05)"
				},
				{
					"name": "Medium",
					"slug": "md",
					"shadow": "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)"
				},
				{
					"name": "Large",
					"slug": "lg",
					"shadow": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)"
				},
				{
					"name": "XL",
					"slug": "xl",
					"shadow": "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)"
				},
				{
					"name": "2XL",
					"slug": "2-xl",
					"shadow": "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)"
				},
				{
					"name": "Inner",
					"slug": "inner",
					"shadow": "inset 0 2px 4px 0 rgb(0 0 0 / 0.05)"
				}
			]
		}
	}
}

目前，这仅在用户界面中为核心按钮块显示阴影选项。可以通过 WordPress 管理后台中的 外观 > 编辑器 > 样式 > 样式指南 访问此控件。从那里，选择按钮块，并在效果选项卡中找到阴影选项，如下图所示：

第三方块也可能利用阴影预设，并在帖子、模板或站点编辑器中的界面中显示它们。

与其他预设一样，您还可以在 theme.json 样式中使用您的自定义阴影（或核心 WordPress 阴影）。

若要深入了解此功能，请阅读 WordPress 开发者博客上的使用 box-shadow 功能为主题。