使用带有 WordPress 块编辑器的设计系统 Pt。 1：主题.json

在我们之前的博客文章中，我们展示了如何将您的设计系统从 Figma 导入到 WordPress 主题的 theme.json 中。 通过这样做，您可以确保整个数字资产的持续一致性。

我们新的两部分系列在此基础上构建，向您展示如何在块编辑器中使用从 theme.json 导入的设计标记。 这将使您能够更好地组织您的 WordPress 网站以反映您的设计系统。 有两个关键目标：

• 了解 theme.json 中与设计系统相关的部分
• 修改和扩展 theme.json 以利用导入的设计系统

了解 theme.json

theme.json 是一个配置文件，允许您配置块编辑器和设置主题、更改块设置以及构建开发整个块主题的基础。

它旨在让您控制 WordPress 网站的全局设置和样式。 每个新的 WordPress VIP 站点都默认带有二十二十三主题，一个块主题。 这个主题是尝试轻量级块主题和了解 theme.json 中可用的一些强大控件的绝佳起点。

修改 theme.json

让我们从上一篇博文中使用的 theme.json 开始。 请注意自定义部分，我们的桥接工具可以在其中插入和更新来自 Figma 的设计系统。 这是您引用设计系统的各种组件（设计令牌）以实际有效使用 theme.json 的关键部分。

下面我们将介绍技巧和策略，以便您可以利用 theme.json 必须提供的一切。

存储设计令牌

虽然可以使用桥接工具自定义设计标记的位置，但它们应始终保留在设置的自定义部分中。 这是桥接工具的默认位置，不应更改。 这样可以将它们正确地组织在一个位置，并可能有助于避免与现有的自定义主题部分发生冲突。

使用设计令牌

让我们看一个使用 theme.json 的自定义部分的示例。 这里我们有一个片段，我们定义了绿色的主要文本颜色和黑色的背景：

 "settings": { "custom": { "text": { "primary": "#00FF00", “background”: “000000” } } } }

这允许我们使用以下方法在 theme.json 中的任何位置引用这两种颜色：

 var(--wp--custom--text--primary) and var(--wp--custom--text--background)

以下代码段确保默认情况下，除非另有说明，否则每个块都将具有黑色背景和绿色文本：

 "styles": { "color": { "text": "var(--wp--custom--text--primary)", “background”: “var(--wp--custom--text--background)” } }

您要从自定义设置中引用的任何键的架构是：

 var(--wp--custom–<location to the value with -- as a separator between each key>)

好处是您可以使用这些键引用所有设计令牌，同时拥有一个管理实际值的中央位置。

最佳实践

• 使用 WordPress 生成的设计标记变量（例如var(--wp--custom--text--primary) ）在任何地方引用标记。 请注意上面提供的代码片段，我们在其中引用主要和背景自定义颜色，而不是使用实际值本身。 这确保了当您想要更新文本颜色等属性时，您只需更改一个位置，因为其他位置只是引用。
• 插入到 theme.json 中的设计标记也可以通过 theme.json 外部的 CSS 访问，使用上面显示的相同键引用。 这适用于块开发和主题中使用的其他组件。 它们并不意味着只能在 theme.json 中使用，应该在任何自定义 CSS 中重复使用。

我们建议遵循这两种最佳实践，以将 theme.json 保持为单一的真实来源。 它将允许您轻松更新设计令牌，尤其是当您使用自动化工具时，例如 WordPress VIP 的连接到 Figma 的桥接工具。

修改编辑器和块样式

上面的代码片段是深入研究自定义块样式方式的好方法。 例如，您可以更改块的默认样式以及可从块编辑器中选择的预设。 当您想要更细化并准确指定站点中使用的内置块的外观时，这很有用。

theme.json中有两个关键位置：

• Settings 和 settings.blocks——允许自定义块编辑器中通常可用的设置，以及为各个块类型定制的设置。
• Styles 和 styles.blocks——允许为整个块编辑器和每个块自定义定义预设样式。

例如，以下是如何确保所有标题都具有默认的绿色（主要）颜色和辅助颜色选项：

 "settings": { "custom": { "text": { "primary": "#00FF00", “secondary”: “#FF0000” } }, “blocks”: { “core/heading”: { “color”: { “text”: true, “palette”: [ { "slug": "primary", "color": "var(--wp--custom--text--primary)", "name": "Primary" }, { "slug": "secondary", "color": "var(--wp--custom--text--secondary)", "name": "Secondary" } ] } } } }, "styles": { "blocks": { “core/heading”: { “color”: { "text": "var(--wp--custom--text--primary)" } } } }

这会将每个标题块配置为具有主要的绿色文本颜色，并添加第二个块编辑器选项以将颜色更改为红色辅助颜色。 注意：这需要一些重复。 样式指定默认的主色，调色板将相同的颜色与辅助色组合在一起，以在块编辑器中提供这两个选项。

造型警告

尽可能只使用 theme.json 的 styles 和 styles.blocks 部分来设置块的样式。 除非绝对需要，否则不要使用 CSS 样式来覆盖核心块样式。 块样式的 CSS 覆盖通常不稳定——块编辑器更新会改变样式和结构，导致这些样式被破坏。

每块定制

虽然上面的示例显示了如何自定义块的设置和样式，但也可以完全禁用自定义并将块编辑器选项限制为特定块。 这对于严格控制哪些选项可用于创建内容、维护设计系统的外观很有用。

让我们继续另一个颜色设置示例，其中相同的原则适用于其他可配置属性，如颜色、排版和间距。 要禁用在除标题块之外的任何地方更改默认文本颜色的功能，可以配置 theme.json 的方法如下：

 "settings": { "custom": { "text": { "primary": "#00FF00", “secondary”: “#FF0000” } }, “color”: { “text”: false }, “blocks”: { “core/heading”: { “color”: { “text”: true, “palette”: [ { "slug": "primary", "color": "var(--wp--custom--text--primary)", "name": "Primary" }, { "slug": "secondary", "color": "var(--wp--custom--text--secondary)", "name": "Secondary" } ] } } } }

此示例显示通过设置配置全局设置，以及通过设置下的块部分配置特定于块的设置。 这也适用于全局样式（在根样式属性下可用）和特定于块的样式（在 styles.blocks 下）。

简单的预设模板

开始创建设计系统的一个好方法是全局锁定块编辑器设置。 之后，您可以逐步启用各个块的设置并控制您的设计系统的外观和感觉，而不会被自定义选项所淹没。首先，这是一组简单的设置，WordPress VIP 的设计系统使用它来全局禁用所有边框、颜色、排版和间距控件默认情况下在编辑器中：

 { "$schema": "https://schemas.wp.org/trunk/theme.json", "version": 2, "settings": { "appearanceTools": true, "border": { "color": false, "radius": false, "style": false, "width": false }, "color": { "text": false, "background": false, "link": false, "custom": false, "defaultPalette": false, "defaultGradients": false, "defaultDuotone": false, "customGradient": false, "customDuotone": false, "palette": [ // Design system palette colors... ], "gradients": [ // Design system gradients... ] }, "spacing": { "margin": false, "padding": false, "units": ["rem", "%"] }, "typography": { "customFontSize": false, "fontStyle": false, "fontWeight": false, "letterSpacing": false, "lineHeight": false, "textDecoration": false, "textTransform": false, "dropCap": false, "fontFamilies": [], "fontSizes": [] } } }

有了这些锁定的默认值，您就可以使用 settings.blocks 在编辑器中公开特定块的选项，并将自定义限制为定义明确的设置。

综上所述

Theme.json 是一个强大的工具，用于组织全局设计标记、设置全局主题样式和自定义单个块。 利用块编辑器为定制公开的所有功能，使设计系统实现集中并与内置块编辑器兼容。

在我们系列的第 2 部分中，我们将介绍 theme.json 之外的更多高级技巧，用于管理设计系统中的内置块类型和样式。

有用的链接

• 什么是 Theme.json？
• 全局设置和样式 (theme.json)

作者

Automattic 高级软件开发人员 Alec Geatches

居住在台湾台北的企业 WordPress 开发人员和设计系统爱好者。

Gopal Krishnan，Automattic 高级软件开发人员

Gopal 致力于 WordPress VIP 的解耦 WordPress 产品，对设计系统和古腾堡感兴趣。 他居住在澳大利亚悉尼，最近刚从加拿大搬来。