云策 WordPress 开发者社区

社区新闻

掌握theme.json：你可能不需要CSS

查看官方原文 ↗ 发布于

我觉得自己越来越懒了。而且我认为 WordPress 的 全局样式 系统对此并无帮助。我只需在 theme.json 或变体的 JSON 文件中填入几个值，它们就会自动限定作用域，仅针对生成的 CSS 中的必要元素或块。这是一个相当简洁的系统。

我们正处于区块主题时代的早期阶段，这将是一个漫长的时代。当然，我仍然会编写相当数量的 CSS——WordPress 目前还不能做所有事情。但随着每个新的 WordPress 主要版本的发布，我发现自己编写的实际 CSS 越来越少，转而使用 JSON 来处理样式。

就我个人而言，我更愿意只写 CSS。主要是因为我已经花了多年时间构建了坚实的样式系统。我可以使用和重用它来得到我想要的东西。但也因为我是个开发者。而这就是开发者该做的事。

但这篇文章不是关于我的。它是关于数百万使用 WordPress 却不懂代码的人。它是关于赋予他们设计自己网站的能力，让我们从民主化发布走向民主化设计。

WordPress 中 全局样式引擎 的真正赢家是用户。因此，我认为样式应该放在哪里，远不如让用户的生活更轻松重要。

在本文中，让我们回顾一下我用来构建区块主题的一些技巧和捷径——你可以把它看作是一种“以防你不知道”的帖子。

我也会告诉你什么时候你绝对需要退回到那个可靠的老 CSS。

利用 JSON 添加全局设置和样式

样式化主题的入口是全局样式系统。你经常会看到它被称为 theme.json。在区块编辑器的早期，theme.json 是唯一可以用 JSON 添加样式规则的地方，因此这成为了引擎本身的简称。但今天，情况已经改变。

现在，就在 WordPress 6.7 发布前几周，样式可以放入几种类型的 JSON 文件中，我们将在下面深入探讨每一种。

有关此系统如何工作的更多信息，请参阅主题手册中的 全局设置和样式 文档。

theme.json 快速概览

WordPress 主题的主要样式应位于主题根文件夹中名为 theme.json 的文件中。可以将其视为主题的基础样式集。每当需要更具体的样式集时（例如，用户样式、区块样式变体），它们会与 theme.json 中的样式合并并优先于后者。

你主题中的 theme.json 文件可以分解为以下顶级键：

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {},
	"styles": {},
	"customTemplates": {},
	"templateParts": {},
	"patterns": []
}

出于本教程的目的，我们将重点关注其中的两个：

  • settings： 一个用于定义用户在界面中可以使用哪些设计工具的对象，但你也可以用它来添加预设（即 CSS 自定义属性）。
  • styles： 一个用于定义根、元素和区块样式的对象，每个选项都映射到 CSS 属性。

你可能已经知道使用 theme.json 的基础知识，那么让我们直接开始添加一些不需要自定义 CSS 的强大功能和技巧。

样式变体的乐趣

目前，区块编辑器允许你在主题中使用四种类型的样式变体：

  • 主题（或“全局”）： 可以覆盖 theme.json 文件的每个方面，包括设置、样式和其他顶级键。
  • 颜色： 可以覆盖颜色设置或样式。
  • 排版： 可以覆盖排版设置或样式。
  • 区块： 可以覆盖特定区块及其嵌套区块和元素的样式。

你必须将任何自定义样式变体 JSON 文件放在主题的 /styles 文件夹下。没有强制性的命名或组织约定，但我建议使用类似这样的嵌套文件夹结构：

/styles
	/block
		/variation-filename.json
	/color
		/variation-filename.json
	/theme
		/variation-filename.json
	/typography
		/variation-filename.json

主题样式变体

主题——通常称为“全局”——变体一直是主题最常见的 样式变体 类型。本质上，它们是主要 theme.json 文件的替代版本，可以做 theme.json 能做的所有事情。

以下是使用默认 theme.json 文件（未选择变体）的站点编辑器页面：

WordPress 站点编辑器显示一个带有定价表的页面。右侧，“浏览样式”面板已打开，显示一个两列的样式网格供选择。

现在，这是同一个页面，但从站点编辑器的样式面板下选择了Saga变体。你会注意到它的样式几乎与默认样式完全不同。例如，它有不同的排版、颜色和边框样式：

WordPress 站点编辑器显示一个带有定价表的页面。右侧，“浏览样式”面板已打开，显示一个两列的样式网格供选择。一个名为 Saga 的自定义样式被选中。

这就是主题样式变体的力量。你可以定义一系列精心策划的样式，让用户选择他们网站的外观，他们只需点击一下就可以做出这些选择。此外，当你将主题变体与颜色和排版变体结合使用时，你为用户提供了前所未有的多种选择。（更多内容见下文。）

为确保 WordPress 能将 JSON 文件识别为主题样式变体，它需要遵循以下规则：

  • 将其放在 /styles 文件夹中（建议放在 /styles/theme 下）。
  • 如果它只有颜色或只有排版样式，它就会变成颜色或排版样式变体。因此，你需要向文件中添加一些其他设置或样式——几乎任何内容都可以。

除此之外，几乎任何内容都可以。在你的主题样式变体文件中定义的任何内容都将覆盖 theme.json 中的相同定义。

例如，这是一个主题样式变体的小示例，它添加了背景颜色、文本颜色，并定义了标题元素的排版：

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"title": "Example",
	"styles": {
		"color": {
			"background": "var:preset|color|white",
			"text": "var:preset|color|black"
		},
		"elements": {
			"heading": {
				"typography": {
					"fontWeight": "700"
				}
			}
		}
	}
}

查看 theme.json 简介 以了解你可以定义的所有设置和样式。

上面代码中的 var:preset|$feature|$slug 语法是 应用预设作为样式 的主要方式。或者，你也可以直接使用 CSS 并引用 var(--wp--preset--$feature--$slug)。

颜色样式变体

在 WordPress 6.6 中添加的 颜色样式变体 可能非常强大。本质上，该功能允许你为用户定义精心策划的调色板预设供其选择，为他们提供快速简单的选项，让他们确信这些选项在主题中有效。

你可以在站点编辑器的样式面板中找到这些变体。下图显示了激活的Evenfall颜色样式变体：

WordPress 站点编辑器，画布中显示一个三列网格，交替使用紫色和粉色。右侧，样式面板已打开，并选择了 Evenfall 调色板。

为确保你的颜色样式变体出现在用户将在界面中看到的位置，请将包含颜色样式的 JSON 文件放在 /styles 文件夹中：

  • 它可能只包含 颜色设置 或样式。
  • 最佳实践：将其放在 /styles/color 下。

想让你的生活更轻松吗？在你编写的所有其他 JSON 文件中，使用与主 theme.json 中定义的相同的键来定义 settings.color 属性——尤其是 palette、duotone 和 gradients。当你编写主题时，你会形成肌肉记忆，即使是在五年没碰过的主题中，你也总能知道你的颜色在哪里。

考虑到这个准则，下面是一个自定义颜色变体可能的样子（当然，请使用与你主题颜色 slug 匹配的 slug）：

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"title": "Evenfall",
	"settings": {
		"color": {
			"palette": [
				{
					"slug": "primary-900",
					"color": "#6e2057",
					"name": "Primary: 900"
				},
				{
					"slug": "primary-700",
					"color": "#b93792",
					"name": "Primary: 700"
				},
				{
					"slug": "primary-500",
					"color": "#d163b0",
					"name": "Primary: 500"
				},
				{
					"slug": "primary-300",
					"color": "#e9b4d9",
					"name": "Primary: 300"
				},
				{
					"slug": "primary-100",
					"color": "#f9ebf5",
					"name": "Primary: 100"
				},
				{
					"slug": "black",
					"color": "#000000",
					"name": "Black"
				},
				{
					"slug": "neutral-900",
					"color": "#1e1b27",
					"name": "Neutral: 900"
				},
				{
					"slug": "neutral-700",
					"color": "#5c5379",
					"name": "Neutral: 700"
				},
				{
					"slug": "neutral-500",
					"color": "#a29aba",
					"name": "Neutral: 500"
				},
				{
					"slug": "neutral-300",
					"color": "#c7c2d6",
					"name": "Neutral: 300"
				},
				{
					"slug": "neutral-100",
					"color": "#ebeaf1",
					"name": "Neutral: 100"
				},
				{
					"slug": "white",
					"color": "#ffffff",
					"name": "White"
				}
			]
		}
	}
}

我的朋友，这就是颜色样式变体无论与什么其他变体搭配都能完美工作的方式。

排版样式变体

排版样式变体 也是 WordPress 6.6 中的新功能。与颜色一样，该功能使你能够为主题添加效果良好的替代字体集——并将它们作为一系列精心策划的预设展示给你的用户，他们只需点击一下即可选择。
排版变体出现在站点编辑器的样式面板中。与颜色一样，它们有自己的面板。下图选择了 Fairy Tale 变体：

WordPress 站点编辑器显示一个带有用户个人资料三列网格的页面。右侧，选择了一个名为 Fairy Tale 的奇幻风格字体集。

就像颜色变体一样，要让 WordPress 将 JSON 文件识别为排版样式变体，需要遵循几条规则：

  • 将其放在 /styles 文件夹中（建议放在 /styles/typography 下）。
  • 它只能包含 排版设置 或样式。

专业提示：通过 settings.typography.fontFamilies 定义字体系列时，在所有变体中使用一致的 slug 命名约定（例如 primary、secondary 等）。这将确保引用的字体系列在所有变体中都有定义。

此代码片段展示了如何定义自定义排版样式变体：

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"title": "Fairy Tale",
	"settings": {
		"typography": {
			"fontFamilies": [
				{
					"fontFamily": "'Elsie Swash Caps', system-ui",
					"slug": "primary",
					"name": "Primary (Elsie Swash Caps)",
					"fontFace": [
						{
							"fontFamily": "Elsie Swash Caps",
							"fontWeight": "400",
							"fontStyle": "normal",
							"fontStretch": "normal",
							"src": [ "file:./public/fonts/elsie/elsie-swash-caps.woff2" ]
						},
						{
							"fontFamily": "Elsie Swash Caps",
							"fontWeight": "900",
							"fontStyle": "normal",
							"fontStretch": "normal",
							"src": [ "file:./public/fonts/elsie/elsie-swash-caps-900.woff2" ]
						}
					]
				},
				{
					"fontFamily": "Lora, Rockwell, 'Rockwell Nova', 'Roboto Slab', 'DejaVu Serif', 'Sitka Small', serif",
					"slug": "secondary",
					"name": "Secondary (Lora)",
					"fontFace": [
						{
							"fontFamily": "Lora",
							"fontWeight": "400 700",
							"fontStyle": "normal",
							"fontStretch": "normal",
							"src": [
								"file:./public/fonts/lora/lora.woff2"
							]
						},
						{
							"fontFamily": "Lora",
							"fontWeight": "400 700",
							"fontStyle": "italic",
							"fontStretch": "normal",
							"src": [
								"file:./public/fonts/lora/lora-italic.woff2"
							]
						}
					]
				}
			]
		}
	},
	"styles": {
		"elements": {
			"button": {
				"typography": {
					"fontFamily": "var:preset|font-family|secondary"
				}
			},
			"caption": {
				"typography": {
					"fontFamily": "var:preset|font-family|primary",
					"fontSize": "var:preset|font-size|sm",
					"fontStyle": "normal",
					"textTransform": "none"
				}
			},
			"heading": {
				"typography": {
					"fontWeight": "400",
					"textTransform": "none"
				}
			}
		},
		"blocks": {
			"core/site-title": {
				"typography": {
					"fontFamily": "var:preset|font-family|primary",
					"fontSize": "var:preset|font-size|lg",
					"fontStyle": "normal",
					"fontWeight": "900",
					"letterSpacing": "0",
					"textTransform": "none"
				}
			}
		}
	}
}

现在，请注意，对于这个变体，我定义的不仅仅是 settings.typography 下的排版预设——我还包括了 styles 属性下元素和块的自定义样式。这与我为颜色所做的完全不同。

原因是：根据我的经验，排版几乎总是需要对其出现的每个地方进行微调。那有很多特定于块和元素的地方。

区块样式变体和区域样式

区块样式变体 已经存在一段时间了。但在 6.6 之前，你必须编写 PHP 并加载自定义样式表。

但现在呢？你可以 定义你的区块样式变体 和区域样式，使用 JSON 文件，就像一个文明人一样。

这个想法是让你构建区域样式，这样你就可以用自定义配色方案来设计群组（以及人们喜欢用作容器的其他块）的样式。但你可以做的远不止这一个小的用例。你可以为任何你想要的块定义 JSON 注册的区块样式。

区域样式

请看下面。这里将样式 3区块样式变体应用于一个群组块，赋予其深蓝色背景和白色文本：

WordPress 页面编辑器显示一个带有蓝色背景和白色文本的区域。它还包括一个山脉照片库。右侧，选择了样式 3 选项，并且悬停在样式 4 选项上显示预览。

同样，要让 WordPress 将 JSON 文件识别为区块样式变体，需要遵循几条规则：

  • 将其放在 /styles 文件夹中（建议放在 /styles/block 下）。
  • 将定义变体的块放在 blockTypes 数组中。

下面是一个名为 section-1 的区块样式的基本示例，它定义了背景和文本颜色：

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"title": "Style 1",
	"slug": "section-1",
	"blockTypes": [
		"core/column",
		"core/columns",
		"core/group"
	],
	"styles": {
		"color": {
			"background": "var:custom|color|primary-700",
			"text": "var:custom|color|text|white"
		}
	}
}

区块样式变体没有像排版和颜色变体那样关于你可以设计什么的具体规则。主要区别在于样式是专门应用于该块以及任何嵌套块或元素的。

注意：社区正在这个新的可互操作主题和变体世界中开始采用一些标准的命名约定。

Twenty Twenty-Five 主题将 开始采用区域样式的约定，但你现在就可以开始使用它。

给你的 slug 加上前缀 section-，然后加上一个数字。就是这样——至少在 slug 中没有其他值。完成后，你将拥有一个逻辑上的区域样式列表，其 slug 为 section-1、section-2 等。

文本样式

从 Twenty Twenty-Five 的工作中产生的另一个约定：用于 纯文本元素 的区块样式变体。其目标是强制（我的意思是，温和地鼓励，以节省他们数小时的时间！）你的用户在开始工作时定义并设计常见的文本元素。

这是一个 kicker。真的：kicker 是位于较大标题上方的一个简短的小标题：

WordPress 文章编辑器，包含一个 kicker（小标题）、较大的标题、段落和一组按钮。

文本样式的工作方式与任何区块样式一样，但约定倾向于将它们应用于标题和段落等块——用户会反复使用的块，并且在上下文中应该始终保持相同的外观。