WordPress 5.8+ 主题编辑器控制文件theme.json详解

WordPress 5.8版本引入了一项创新机制，旨在为编辑器配置提供更精细化的控制，并开启了未来版本样式管理的先河。这一新机制不仅增强了编辑器的可定制性，还为开发者和机构提供了更强大的控制能力，从而实现更加统一和完整的用户体验。

### 全局与块级控制设置

WordPress 5.8中的新机制允许对编辑器进行全局和每个块级别的设置控制。通过`useSetting`函数，开发者可以轻松访问主题设置预设的CSS类，这些类会自动创建并加入队列，从而简化了样式的管理过程。这一改进显著提升了样式的协调性，并为访问其他编辑器功能奠定了基础。

### 主题配置文件theme.json

为了进一步简化编辑器的配置，WordPress 5.8引入了`theme.json`文件。在主题的顶级目录中创建此文件，开发者可以配置现有的编辑器设置（如字体大小预设、自定义颜色启用等）以及引入的新设置（如双色调预设、边距和填充控件启用等）。这一机制旨在整合所有以前控制编辑器所需的`add_theme_support`调用，从而简化了主题开发流程。

以下示例展示了如何通过`theme.json`禁用所有块的自定义颜色：

“`json
{
“version”: 1,
“settings”: {
“color”: {
“custom”: false
}
}
}
“`

同时，该文件还支持基于每个块控制这些设置，这在以前是不可能的。例如，以下示例展示了如何禁用所有块的自定义颜色，但为段落块启用它们：

“`json
{
“version”: 1,
“settings”: {
“color”: {
“custom”: false
},
“blocks”: {
“core/paragraph”: {
“color”: {
“custom”: true
}
}
}
}
}
“`

### 样式优先级与覆盖

在`theme.json`中声明的设置将优先于`add_theme_support`的设置，确保了样式的灵活性和可控性。例如，如果主题使用`add_theme_support(‘disable-custom-colors’)`，其效果等同于将`settings.color.custom`设置为`false`。为了保持向后兼容性，现有的`add_theme_support`声明在顶级部分的适当类别中进行了改造。

### 核心与第三方块的设置

核心块已更新以尊重来自主题的新设置`theme.json`。例如，如果某个块支持UI边距控件，但主题已全面禁用边距，则该UI控件将不会显示在编辑器中。第三方块也可以通过在其编辑功能中使用`useSetting` React钩子来利用这种机制：

“`javascript
import { useSetting } from ‘@wordpress/block-editor’;

// Somewhere in the block’s edit function.
const isEnabled = useSetting(‘spacing.margin’);
if (!isEnabled) {
return null;
} else {
return;
}
“`

### 预设CSS类的自动创建与排队

以前，主题必须为编辑器声明预设，并分别将相应的类排入队列。在`functions.php`文件中，开发者会这样做：

“`php
add_theme_support(‘editor-color-palette’, array(/* define color presets, including translations */));
“`

然后在`style.css`中定义相应的样式：

“`css
.has–color {
/* … */
}
.has–background-color {
/* … */
}
/* etc */
“`

通过使用`theme.json`，主题只需要声明他们的预设，引擎将自动设置翻译，并负责为编辑器和前端创建和排队相应的样式：

“`json
{
“version”: 1,
“settings”: {
“color”: {
“palette”: [
{
“name”: “Color name”,
“slug”: “color-slug”,
“color”: “”
},
{
“name”: “…”,
“slug”: “…”,
“color”: “…”
}
]
}
}
}
“`

### CSS自定义属性的使用

随着IE11支持的逐步淘汰，许多CSS功能变得可用，其中之一就是CSS自定义属性。当主题通过`theme.json`添加预设时，引擎会将类和CSS自定义属性排入队列。以下是一个示例：

“`json
{
“version”: 1,
“settings”: {
“color”: {
“palette”: [
{
“name”: “Black”,
“slug”: “black”,
“color”: “#000000”
},
{
“name”: “White”,
“slug”: “white”,
“color”: “#ffffff”
}
]
}
}
}
“`

这将生成以下CSS输出：

“`css
/* One CSS Custom Property per preset value. */
body {
–wp–preset–color–black: #000000;
–wp–preset–color–white: #ffffff;
}

/* The corresponding classes for each preset value. */
.has-black-color {
color: var(–wp–preset–color–black) !important;
}
.has-black-background-color {
background-color: var(–wp–preset–color–black) !important;
}
.has-white-color {
color: var(–wp–preset–color–white) !important;
}
.has-white-background-color {
background-color: var(–wp–preset–color–white) !important;
}
“`

### 管理样式以提高协调性

主题作者在处理核心、主题和用户样式时常常面临样式冲突的难题，尤其是在设计区域可以无限组合多个块的情况下。`theme.json`文件通过吸收样式块的大部分常见用例，旨在减少传送到浏览器的CSS数量、减轻冲突，并在UI控件中为用户提供当前样式信息。这是整合所有三个样式来源（核心、主题、用户）的第一步，未来用户可以在项目的后期阶段提供全局样式，进一步提升用户体验。

以下示例展示了主题为顶级和几个块提供样式：

“`json
{
“version”: 1,
“styles”: {
“color”: {
“text”: “var(–wp–preset–color–primary)”
},
“blocks”: {
“core/paragraph”: {
“color”: {
“text”: “var(–wp–preset–color–secondary)”
}
},
“core/group”: {
“color”: {
“text”: “var(–wp–preset–color–tertiary)”
}
}
}
}
}
“`

这将生成以下CSS输出：

“`css
/* Top-level styles resolve to the body selector. */
body {
color: var(–wp–preset–color–primary);
}

/* Block styles resolve to the block selector. */
p {
color: var(–wp–preset–color–secondary);
}
.wp-block-group {
color: var(–wp–preset–color–tertiary);
}
“`

任何块，包括核心块和第三方块，都可以以其名称为目标。有关受支持样式的完整列表，请参阅规范文档。

### 访问其他功能

当主题支持`theme.json`文件时，会启用或禁用一些功能，例如：

– 模板编辑器启用。
– 主题的默认布局和边距样式不会排队，而是启用新的布局选项。
– 组块（`wp-block-group__inner-container`）的内部`div`被删除。
– 编辑器的`font-family`默认样式不排队。

继续阅读：WordPress 5.8+ 设置布局和内容宽度的新方式。