全局设置和样式（theme.json）–块编辑器手册|开发人员。WordPress.org网站

WordPress 5.8附带一种新的机制要配置启用细粒度控件的编辑器，并引入管理未来WordPress版本样式的第一步：主题.json文件。

理论基础

块编辑器API以不同的速度发展，尤其是在影响主题的领域，存在一些成长困难。例如：以编程方式控制编辑器，或块样式系统这有助于用户、主题和核心风格偏好。

这描述了当前将与样式相关的各种API整合为一个点的工作–主题.json应该位于主题目录根目录内的文件。

块编辑器的设置

与主题支持标志或替代方法的扩散不同主题.json文件提供了定义块编辑器设置的规范方法。这些设置包括以下内容：

应该向用户提供或隐藏哪些自定义选项。
用户可以使用的默认颜色、字体大小……是什么。
定义编辑器的默认布局（宽度和可用路线）。

可以按块控制设置

为了获得更高的粒度，这些设置也适用于主题.json.

可以实现的目标包括：

对块（例如：表）使用特定预设，但对其余块使用通用预设。
为所有块（标题块除外）启用字体大小UI控件。
等。

管理样式

通过使用主题.json文件以结构化方式设置样式属性，块编辑器可以“管理”来自不同来源（用户、主题和核心CSS）的CSS。例如，如果一个主题和一个用户为段落设置了字体大小，那么我们只对来自用户而不是主题的样式进行排队。

其优点包括：

减少CSS排队的数量。
防止特殊战争。

CSS自定义属性：预设和自定义

有一些样式化领域可以从共享值中受益，这些值可以在整个站点中更改。

为了满足这一需求，我们已经开始在一些地方试验CSS自定义属性，也称为CSS变量：

预设:调色板,字体大小，或梯度由主题声明的将转换为CSS自定义属性，并将前端和编辑器排入队列。

{“版本”：3，“设置”：{“颜色”：{“调色板”：[{“name”：“黑色”，“slug”：“黑色”，“颜色”：“#000000”},{“name”：“白色”，“slug”：“白色”，“颜色”：“#ffffff”}]}}}

车身{--wp——预设——颜色——黑色：#000000；--wp--预设--颜色--白色：#ffffff；}

自定义属性：还有一种创建自己的CSS自定义属性的机制。

{“版本”：3，“设置”：{“自定义”：{“线条高度”：{“主体”：1.7，“标题”：1.3}}}}

车身{--wp——自定义——线高——正文：1.7；--wp——自定义——线条高度——标题：1.3；}

添加主题支持	theme.json设置
`定制线路高度`	设置`typegraphy.line高度`到`真的`.
`自定义间距`	设置`间距填充`到`真的`.
`自定义单位`	通过以下方式提供单位列表`间距单位`.
`禁用自定义颜色`	设置`颜色.自定义`到`假`.
`禁用自定义尺寸`	设置`排版.customFontSize`到`假`.
`禁用粗粒料`	设置`颜色自定义渐变`到`假`.
`编辑器调色板`	通过提供颜色列表`彩色套色`.
`编辑字体大小`	通过提供字体大小列表`印刷字体大小`.
`编辑器粒度预设`	通过提供梯度列表`颜色.渐变`.
`编辑器空间大小`	通过提供间距尺寸列表`间距。间距大小`.
`外观-工具`	设置`外观工具`到`真的`.
`边境`	设置`边框：颜色、半径、样式、宽度`到`真的`.
`链接颜色`	设置`颜色链接`到`真的`.

在此字段中，主题可以列出部分文件夹。例如，对于名为my-template-part.html，的主题.json可以为模板零件实体声明区域术语，该实体负责在编辑器中呈现相应的块变体（页眉块、页脚块等）。在json中定义此区域术语将允许该设置在该模板零件实体的所有使用中保持不变，而不是只影响一个块的块属性。不建议将区域定义为块属性，因为这仅用于“幕后”，以帮助弥合占位符流和实体创建之间的差距。

目前，区域术语的“页眉”和“页脚”值存在块变体，json中未定义的任何其他值和模板部件将默认为通用模板部件块。变体将由编辑器界面中的特定图标表示，默认为包装器的相应语义HTML元素（这也可以被标记名属性集），并将模板部分上下文化，以便在未来的编辑器改进中允许更多自定义流。

名称：必填。
标题：可选，可翻译。
区域：可选，将设置为未分类的默认情况下，不会触发块变化。

{“版本”：3，“模板部件”：[{“name”：“my-template-part”，“title”：“标题”，“区域”：“标题”}]}

模式

WordPress 6.0版支持。

在此字段中，主题可以列出要注册的模式模式目录. The模式字段是模式数组鼻涕虫从模式目录。模式段塞可以通过网址在模式目录的单一模式视图中。例如，在此url中https://wordpress.org/patterns/pattern/partner-logos`鼻涕是partner-logos合作伙伴。

{“版本”：3，“patterns”：[“shorttext-surrounded-by-round-images”，“partner-logos”]}

使用theme.json开发

很难记住theme.json的设置和属性，以及在开发时WordPress的哪些版本支持哪些设置，因此为theme.j森使用提供的json模式会很有帮助。

许多代码编辑器支持JSON模式，并可以在编辑器中提供工具提示、自动补全或模式验证等帮助。

每个WordPress版本的Theme.json模式可在https://schemas.wp.org/wp/{{version}}/theme.json`。例如，WordPress 5.8的模式可在https://schemas.wp.org/wp/5.8/theme.json网站`. 为了确保您只使用用户可用的功能，最好使用您的主题支持的最旧版本。

包含Gutenberg插件所有最新更改的最新模式可从以下网址获得：`https://schemas.wp.org/trunk/theme.json网站`.

检查编辑器文档中的JSON模式支持。例如，在Visual Studio代码中，您需要添加“$schema”：“https://schemas.wp.org/wp/x.x/theme.json网站"作为您的theme.json文件的顶级属性，但其他编辑器的配置可能不同。

使用模式验证的示例

常见问题

CSS自定义属性的命名模式

您可能已经注意到，系统创建的CSS自定义属性使用了命名模式，包括使用双连字符，--，以分离不同的“概念”。以下面的例子为例。

预设例如--wp--预设--颜色--黑色可以分为以下组块：

--水处理：前缀，用于命名CSS变量的名称空间。
预设：表示是属于预设的CSS变量。
颜色：表示变量所属的预置类别。可以是颜色,字体大小,梯度.
黑色：的段塞特定预设值。

自定义属性，例如--wp--自定义--线高--正文，可分为以下几个部分：

--水处理：为CSS变量命名的前缀。
习俗：表示由主题创建的“自由形式”CSS变量。
线高--主体：将“自定义”对象键转换为字符串的结果。

这个--作为分隔符有两个功能：

可读性，便于人类理解。可以认为它类似于BEM命名模式，它分离“类别”。
可解析性，便于机器理解。使用定义的结构可以让机器理解属性的含义--wp--预设--颜色--黑色：它是一个绑定到颜色预设的值，其slug为“black”，这样我们就有空间对其进行更多操作。

为什么使用-作为分隔符？

我们可以使用任何其他分隔符，例如单个-.

然而，这是有问题的，因为不可能知道如何--wp-custom-line高模板标头应该转换回对象，除非我们强制主题作者不使用-在变量名中。

通过预订--作为类别分隔符，并让主题作者使用-对于单词边界，命名更清晰：--wp--自定义--线宽--模板标头.

“自定义”下的设置如何创建新的CSS自定义属性

根据“custom”键下的设置创建CSS变量的算法是这样工作的：

这是为了清楚起见，但也因为我们需要一种机制来解析回变量名，例如--wp--自定义--线高--正文转换为主题.json中的对象形式。我们对预设使用相同的分隔。

例如：

{“版本”：3，“设置”：{“自定义”：{“线条高度”：{“主体”：1.7},“font-primary”：“-apple-system，BlinkMacSystemFont，'Segoe UI'，Roboto，Oxygen-Sans，Ubuntu，Cantarell，'Helvetica Neue'，Sans-serif”}}}

车身{--wp——自定义——线高——正文：1.7；--wp--custom--font-primary:“-apple-system，BlinkMacSystemFont，'Segoe UI'，Roboto，Oxygen-Sans，Ubuntu，Cantarell，'Helvetica Neue'，Sans-serif”；}

关于此过程的几点注意事项：

带骆驼皮的键转换为其烤肉串表单，以遵循CSS属性命名模式。例子：线条高度被转化为线路高度.
不同深度级别的关键点由--.这就是为什么线路高度和身体被隔开--.
你不应该使用--在键的名称中习俗对象。例子，不要这样做这个：

{“版本”：3，“设置”：{“自定义”：{“线条--高度”：{//请勿这样做“主体”：1.7}}}}

全球样式表

在WordPress 5.8中，对于大多数主题，WordPres定义的一些预设（字体大小、颜色和渐变）的CSS加载了两次：在块库样式表中，再加上在全局样式表中。此外，这两个地方的CSS略有不同。

在WordPress 5.9版本中，预置的CSS被合并到全局样式表中，现在可以为所有主题加载。每个预设值都会生成一个CSS自定义属性和一个类，如下所示：

/*预设值的CSS自定义属性*/车身{--wp—预设-->preset_TYPE>-->preset_SLUG>：<DEFAULT_VALUE>；--wp--预设--颜色--淡色墨水：#f78da7；--wp——预设——字体大小——大：36px；/*等*/}/*预设值的CSS类*/.具有-<PRESET_SLUG>-<PRETET_TYPE>{…}.has-pale-pink-color{color:var（--wp-预设--color--pale-pink）！重要；}.has-large-font-size{font-size:var（--wp-预设--font-size-大）！important；}

对于要覆盖默认值的主题，可以使用主题.json并提供相同的段塞。不使用主题.json仍然可以通过将一些设置相应CSS自定义属性的CSS排入队列来覆盖默认值。

例子（为默认的大字体设置一个新值）：

车身{--wp—预设--字体大小--大：<NEW_VALUE>；}

用户提供的链接颜色的特定性

在WordPress 5.8中，当用户为特定块选择链接颜色时，我们以以下形式将类附加到该块.wp-element-<ID>然后将以下样式排入队列：

.wp-element-<ID>a{color:<USER_color_VALUE>！important；}

虽然这始终保留了用户的首选项，但其特定性太强，与合法使用HTML元素的某些块冲突，HTML元素不应被视为链接。收件人解决这个问题，在WordPress 5.9版本中!重要的删除并更新了相应的块，以使a元素具有比用户链接颜色更高的特异性，即：

.wp-element-<ID>a{color:<USER_color_VALUE>；}

由于此更改，现在区块作者和主题作者有责任确保始终尊重用户的选择，并且用户提供的链接颜色（特异性011）不会被覆盖。

什么是blockGap？我如何使用它？

对于包含内部块的块，例如组、列、按钮和社交图标，块间隙控制内部块之间的间距。对于块间隙为了工作，区块还必须选择加入布局块式支架，它提供可以通过块间距控件调整的布局样式。根据块的布局块间隙值将输出为垂直边距或缺口值。在编辑器中块间隙值被调用块间距，位于“尺寸”面板中。

{“版本”：3，“设置”：{“间距”：{“blockGap”：true，}},“样式”：{“间距”：{“块间隙”：“1.5rem”}}}

的设置块间隙是布尔值或无效的值和为无效的默认情况下。这允许对样式输出进行额外级别的控制。这个settings.spaceing.block间隙在中设置主题.json文件接受以下值：

真的：选择显示块间距编辑器UI和输出中的控件块间隙样式。
假：选择退出显示块间距编辑器UI中的控件，带有块间隙存储在中的样式主题.json仍在渲染中。这允许主题使用块间隙值，而不允许用户在编辑器中进行更改。
无效的（默认）：选择不显示块间距控制，和防止输出块间隙样式。

为根定义的值样式.spacing.blockGap样式也输出为CSS属性，名为--wp--样式--块映射.

为什么更新浏览器中的样式需要这么长时间？

当您积极使用theme.json进行开发时，您可能会注意到您的更改需要30多秒才能显示在浏览器中，这是因为主题.json已缓存。要删除此缓存问题，请设置WP_DEBUG公司或脚本_取消在您的wp-config.php这告诉WordPress跳过缓存并始终使用新数据。

全局设置和样式（theme.json）

在本文中

理论基础

块编辑器的设置

可以按块控制设置

管理样式

CSS自定义属性：预设和自定义

规范

版本

设置

选择加入UI控件

与add_theme_support向后兼容

预设

自定义

设置示例

样式

顶级风格

块样式

引用样式

元素样式

元素伪选择器

变化

自定义模板

模板部件

模式