The settings.custom property 在 theme.json 中的其他设置中是独一无二的。顾名思义，它是一个自定义属性。这意味着您可以决定如何使用它。本质上，它提供了一种创建您可能需要在主题的其他地方使用的 CSS 自定义属性的方法。

在本文档中，您将了解 custom 属性的用途以及如何在您的主题中使用它。

自定义设置概述

settings.custom 属性接受单个对象，该对象可用于存储其他值。单个对象值必须是有效的 CSS 值或具有嵌套键/值对的对象。

以下是 theme.json 中未设置任何自定义值的示例片段：

{
	"version": 2,
	"settings": {
		"custom": {}
	}
}

settings.custom 对象的好处是，您可以使用它来创建自己的 CSS 自定义属性。当您向对象添加键和值时，WordPress 将自动生成 CSS 自定义属性、分配该值并为您加载它。

生成的 CSS 自定义属性将遵循以下模式：--wp--custom--{key}--{value}。

假设您想使用键 fruit 并将其值设为 apple。将此内容添加到您的 theme.json 文件中：

{
	"version": 2,
	"settings": {
		"custom": {
			"fruit": "apple"
		}
	}
}

WordPress 将生成以下 CSS：

body {
	--wp--custom--fruit: apple;
}

CSS 自定义属性的生成方式

如上所述，settings.custom.fruit 键名将生成 CSS 中的 --wp--custom--fruit 变量。但也存在其他情况。

自动连字符化

WordPress 会自动对驼峰式命名的名称进行连字符化处理。例如，以下示例中的 lineHeight 将变为 line-height：

{
	"version": 2,
	"settings": {
		"custom": {
			"lineHeight": "1.4em"
		}
	}
}

这将创建以下 CSS：

body {
	--wp--custom--line-height: 1.4em;
}

当用作键时，数字的处理方式与大写字母相同。例如，键 abc123 在生成的 CSS 中将变为 abc-1-2-3。

嵌套属性

基于上述示例，假设您想为您的主题创建几个行高 CSS 自定义属性。为此，您可能想在 settings.custom.lineHeight 下创建一个对象，而不是单个值。

将以下内容添加到您的 theme.json 文件中：

{
	"version": 2,
	"settings": {
		"custom": {
			"lineHeight": {
				"xs": "1",
				"sm": "1.25",
				"md": "1.5",
				"lg": "1.75"
			}
		}
	}
}

WordPress 将在生成 CSS 自定义属性名称时自动使用此嵌套结构。

这将生成以下 CSS：

body {
	--wp--custom--line-height--xs: 1;
	--wp--custom--line-height--sm: 1.25;
	--wp--custom--line-height--md: 1.5;
	--wp--custom--line-height--lg: 1.75;
}

嵌套的深度没有限制，但请记住，嵌套越多，您的 CSS 自定义属性名称就越长。

实际用法

settings.custom 属性的用途完全由您决定。从根本上说，它实际上只是生成 CSS 自定义属性，而这些属性本身不会做任何事情。自定义属性也必须用于 CSS 中。

在上面的 theme.json 示例中，您创建了一组行高。有几种方法可以将这些内容投入实际使用。

在 theme.json 样式中使用

在样式文档中，您将学习如何通过 theme.json 将样式应用于根元素、元素和块。这将是与 settings.custom 集成的主要用例之一。

假设您想注册上面的一组行高并使用它们。也许您希望将根元素的行高设置为 md，将段落块的行高设置为 lg。您可以通过 var:custom|line-height|md 和 var:custom|line-height|lg 分别访问每个行高属性。

将此代码放入您的 theme.json 文件中：

{
	"version": 2,
	"settings": {
		"custom": {
			"lineHeight": {
				"xs": "1",
				"sm": "1.25",
				"md": "1.5",
				"lg": "1.75"
			}
		}
	},
	"styles": {
		"typography": {
			"lineHeight": "var:custom|line-height|md"
		}
		"blocks": {
			"core/paragraph": {
				"typography": {
					"lineHeight": "var:custom|line-height|lg"
				}
			}
		}
	}
}

您也可以通过 CSS 自定义属性引用这些值。例如，不使用 var:custom|line-height|md，而是使用 var( --wp--custom--line-height--md )。

请记住，您将从样式文档中了解有关通过 theme.json 进行样式的更多信息。您可以使用在那里学到的内容来结合此处概述的技术。

在 CSS 中使用

有时您可能需要在 CSS 中直接引用生成的 CSS 自定义属性，例如您的 style.css 文件。为此，您必须使用 CSS 自定义属性名称。

假设您需要针对名为 .example-class 的类，并赋予您已注册的 sm 行高。将此代码放入您的 CSS 中：

.example-class {
	line-height: var( --wp--custom--line-height--sm );
}