### 用户自定义链接颜色的特异性处理

在WordPress 5.8版本中，当用户为特定区块选择链接颜色时，系统会为该区块附加一个`.wp-element-<ID>`类，并加入以下样式：

```css
.wp-element-<ID> a { color: <用户颜色值> !important; }
```

虽然这种方式始终保留了用户偏好设置，但过高的特异性会导致与某些合法使用HTML元素的区块产生冲突。为解决该问题，WordPress 5.9版本移除了`!important`声明，并更新了相关区块的样式设置，使其具有比用户链接颜色设置更高的特异性。调整后的样式为：

```css
.wp-element-<ID> a { color: <用户颜色值>; }
```

此项调整后，区块开发者和主题开发者需要确保用户设置始终生效，避免用户提供的链接颜色（特异性值为011）被意外覆盖。

### 什么是blockGap及其应用方式

对于包含内部区块的组件（如群组、列、按钮组、社交图标等），`blockGap`用于控制内部区块之间的间距。要使`blockGap`生效，区块必须启用布局区块支持功能，该功能提供可通过区块间距控件调整的布局样式。根据区块布局的不同，`blockGap`值将作为垂直边距或CSS网格间隙值输出。在编辑器中，`blockGap`的控制选项名为"区块间距"，位于尺寸设置面板中。

```json
{
	"version": 3,
	"settings": {
		"spacing": {
			"blockGap": true,
		}
	},
	"styles": {
		"spacing": {
			"blockGap": "1.5rem"
		}
	}
}
```

`blockGap`设置支持布尔值或`null`，默认值为`null`，这为样式输出提供了更精细的控制层级。在`theme.json`文件中，`settings.spacing.blockGap`设置接受以下参数：

- `true`：启用编辑器界面中的"区块间距"控件，并输出`blockGap`样式
- `false`：禁用编辑器界面中的"区块间距"控件，但仍会渲染存储在`theme.json`中的`blockGap`样式，允许主题使用`blockGap`值的同时限制用户在编辑器中进行修改
- `null`（默认值）：同时禁用"区块间距"控件和`blockGap`样式输出

根级别`styles.spacing.blockGap`样式定义的值同时会作为CSS自定义属性输出，其命名为`--wp--style--block-gap`。

### 浏览器样式更新延迟的原因分析

在使用theme.json进行主题开发时，您可能会注意到样式更改需要30秒以上才能在浏览器中显示，这是因为`theme.json`存在缓存机制。要解决此缓存问题，请在`wp-config.php`文件中将`WP_DEBUG`或`SCRIPT_DEBUG`设置为'true'。这将指示WordPress跳过缓存并始终使用最新数据。

# 全局设置与样式 (theme.json)

WordPress 5.8 引入了一套[全新机制](https://make.wordpress.org/core/2021/06/25/introducing-theme-json-in-wordpress-5-8/)来配置编辑器，该机制支持更精细化的控制，并为未来WordPress版本的样式管理迈出了第一步：即通过`theme.json`文件实现。

## 设计理念

区块编辑器API在不同层面的演进速度不一，尤其在影响主题功能的领域出现了一些发展阵痛。例如：[通过编程方式控制编辑器](https://make.wordpress.org/core/2020/01/23/controlling-the-block-editor/)的能力，或是能够协调用户、主题和核心样式偏好的[区块样式系统](https://github.com/WordPress/gutenberg/issues/9534)。

当前我们正致力于将多个与样式相关的API整合至统一入口——即放置在主题目录根路径下的`theme.json`文件。

### 区块编辑器设置

相较于不断新增的主题支持标志或替代方案，`theme.json`文件提供了定义区块编辑器设置的标准化方式。这些设置包括：

-   应向用户显示或隐藏哪些自定义选项
-   用户可使用的默认颜色、字体大小等配置
-   定义编辑器的默认布局（宽度和对齐方式）

### 支持按区块精细控制

为实现更精细的调控，这些设置同样支持在`theme.json`中针对特定区块进行配置。例如：

-   为特定区块（如表格）使用专属预设，其余区块使用通用预设
-   为除标题区块外的所有区块启用字体大小UI控件
-   等等

### 集中化管理样式

通过结构化方式在`theme.json`文件中设置样式属性，区块编辑器能够统筹管理来自不同来源（用户、主题和核心CSS）的CSS。例如当主题和用户同时设置段落字体大小时，系统只会加载用户设置的样式而非主题样式。

这样做的好处包括：

-   减少CSS加载量
-   避免样式优先级冲突

### CSS自定义属性：预设与自定义

某些样式领域需要通过共享值来实现全站统一调整，为此我们开始在部分场景中实验CSS自定义属性（即CSS变量）：

- **预设配置**：主题声明的[色彩调色板](/docs/how-to-guides/themes/theme-support.md#block-color-palettes)、[字体尺寸](/docs/how-to-guides/themes/theme-support.md#block-font-sizes)或[渐变效果](/docs/how-to-guides/themes/theme-support.md#block-gradient-presets)会被转换为CSS自定义属性，同时在前端和编辑器中加载。

{% codetabs %}
{% 输入 %}

```json
{
	"version": 3,
	"settings": {
		"color": {
			"palette": [
				{
					"name": "黑色",
					"slug": "black",
					"color": "#000000"
				},
				{
					"name": "白色",
					"slug": "white",
					"color": "#ffffff"
				}
			]
		}
	}
}
```

{% 输出 %}

```css
body {
	--wp--preset--color--black: #000000;
	--wp--preset--color--white: #ffffff;
}
```

{% end %}

- **自定义属性**：系统还提供了创建自定义CSS属性的机制。

{% codetabs %}
{% 输入 %}

```json
{
	"version": 3,
	"settings": {
		"custom": {
			"line-height": {
				"body": 1.7,
				"heading": 1.3
			}
		}
	}
}
```

{% 输出 %}

```css
body {
	--wp--custom--line-height--body: 1.7;
	--wp--custom--line-height--heading: 1.3;
}
```

{% end %}

## 技术规范

本规范适用于使用此格式的三大来源：核心系统、主题和用户。主题可通过创建`theme.json`文件来覆盖核心默认设置。用户则可通过正在开发中的站点编辑器界面，覆盖主题或核心的预设配置。

```json
{
	"version": 3,
	"settings": {},
	"styles": {},
	"customTemplates": {},
	"templateParts": {}
}
```

### 自定义模板

<div class="callout callout-alert">自 WordPress 5.9 版本起支持。</div>

在此字段中，主题可以列出 `templates` 文件夹中的自定义模板。例如，对于名为 `my-custom-template.html` 的自定义模板，`theme.json` 可以声明哪些文章类型可以使用它以及向用户显示的标题：

- name：必需。
- title：必需，可翻译。
- postTypes：可选，默认仅适用于 `page`。

```json
{
    "version": 3,
	"customTemplates": [
		{
			"name": "my-custom-template",
			"title": "模板标题",
			"postTypes": [
				"page",
				"post",
				"my-cpt"
			]
		}
	]
}
```

### 模板部件

<div class="callout callout-alert">自 WordPress 5.9 版本起支持。</div>

在此字段中，主题可以列出 `parts` 文件夹中的模板部件。例如，对于名为 `my-template-part.html` 的模板部件，`theme.json` 可以声明模板部件实体的区域术语，该术语负责在编辑器中渲染相应的区块变体（如页眉区块、页脚区块等）。在 JSON 中定义此区域术语将使该设置在该模板部件实体的所有使用中保持一致，而区块属性仅影响单个区块。不建议将区域作为区块属性定义，因为这仅用于“幕后”辅助占位符流程与实体创建之间的衔接。

目前，区域术语的“header”和“footer”值存在区块变体，任何其他值以及未在 JSON 中定义的模板部件将默认为通用模板部件区块。变体将在编辑器界面中通过特定图标表示，默认使用对应的语义化 HTML 元素作为包装器（这也可以通过模板部件区块上设置的 `tagName` 属性覆盖），并将模板部件上下文化，以便在未来的编辑器改进中实现更自定义的流程。

- name：必需。
- title：可选，可翻译。
- area：可选，默认为 `uncategorized`，且不会触发区块变体。

```json
{
    "version": 3,
	"templateParts": [
		{
			"name": "my-template-part",
			"title": "页眉",
			"area": "header"
		}
	]
}
```

### 模式

<div class="callout callout-alert">自 WordPress 6.0 版本起支持。</div>

在此字段中，主题可以列出要从[模式目录](https://wordpress.org/patterns/)注册的模式。`patterns` 字段是模式目录中的模式 `slugs` 数组。模式 slugs 可以从模式目录中单个模式视图的 `url` 中提取。例如，在 URL `https://wordpress.org/patterns/pattern/partner-logos` 中，slug 为 `partner-logos`。

```json
{
	"version": 3,
	"patterns": [ "short-text-surrounded-by-round-images", "partner-logos" ]
}
```

## 使用 theme.json 进行开发

在开发过程中，可能难以记住 theme.json 的设置和属性以及不同 WordPress 版本支持哪些设置，因此使用提供的 theme.json 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 Code 中，您需要在 theme.json 文件的顶级属性中添加 `"$schema": "https://schemas.wp.org/wp/x.x/theme.json"`，但其他编辑器的配置可能不同。

![使用模式验证的示例](https://developer.wordpress.org/files/2021/11/theme-json-schema-updated.gif)

## 常见问题解答

### CSS自定义属性的命名规范

您可能已经注意到系统创建的CSS自定义属性采用了特定的命名规范，包括使用双连字符`--`来分隔不同"概念"。请看以下示例：

**预设属性**（如`--wp--preset--color--black`）可拆分为以下部分：
- `--wp`：命名空间前缀
- `preset`：标识属于预设值的CSS变量
- `color`：指示变量所属的预设类别（可以是`color`、`font-size`、`gradients`）
- `black`：特定预设值的标识符

**自定义属性**（如`--wp--custom--line-height--body`）可拆分为：
- `--wp`：命名空间前缀
- `custom`：标识由主题创建的"自由形式"CSS变量
- `line-height--body`：将"custom"对象键名转换后的字符串结果

双连字符`--`作为分隔符具有双重作用：
- 增强人类可读性：类似于BEM命名规范，用于区分不同"类别"
- 提升机器可解析性：通过既定结构让机器理解属性含义，例如能识别`--wp--preset--color--black`是绑定到标识符为"black"的色彩预设值，为后续操作留出空间

### 为何选用`--`作为分隔符？

理论上可以使用其他分隔符（如单连字符`-`），但这会产生问题：除非强制主题作者不在变量名中使用`-`，否则无法将`--wp-custom-line-height-template-header`准确转换回对象形式。

通过保留`--`作为类别分隔符，并允许主题作者使用`-`作为单词边界，命名将更加清晰：`--wp--custom--line-height--template-header`

### "custom"配置如何生成CSS自定义属性

从"custom"配置项生成CSS变量的算法原理如下（以示例说明）：

{% codetabs %}
{% 输入 %}

```json
{
	"version": 3,
	"settings": {
		"custom": {
			"lineHeight": {
				"body": 1.7
			},
			"font-primary": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif"
		}
	}
}
```

{% 输出 %}

```css
body {
	--wp--custom--line-height--body: 1.7;
	--wp--custom--font-primary: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif";
}
```
{% end %}

注意事项：
- 驼峰式命名的键名会转换为短横线命名法（如`lineHeight`转为`line-height`），遵循CSS属性命名规范
- 不同层级的键名通过`--`分隔（这就是`line-height`与`body`之间使用`--`的原因）
- 禁止在`custom`对象的键名中使用`--`（错误示例如下）：

```json
{
	"version": 3,
	"settings": {
		"custom": {
			"line--height": { // 禁止此种写法
				"body": 1.7
			}
		}
	}
}
```

### 全局样式表

WordPress 5.8版本中，WordPress定义的预设样式（字体大小、颜色和渐变）在多数主题中会重复加载：既通过区块库样式表加载，又通过全局样式表加载，且两处CSS存在细微差异。

WordPress 5.9版本将预设样式的CSS统一整合到全局样式表中，该样式表现已为所有主题加载。每个预设值会生成单个CSS自定义属性和对应类：

```css
/* 预设值的CSS自定义属性 */
body {
  --wp--preset--<预设类型>--<预设标识>: <默认值>;
  --wp--preset--color--pale-pink: #f78da7;
  --wp--preset--font-size--large: 36px;
  /* 其他属性 */
}

/* 预设值的CSS类 */
.has-<预设标识>-<预设类型> { ... }
.has-pale-pink-color { color: var(--wp--preset--color--pale-pink) !important; }
.has-large-font-size { font-size: var(--wp--preset--font-size--large) !important; }
```

主题如需覆盖默认值，可通过`theme.json`文件提供相同标识符进行配置。未使用`theme.json`的主题仍可通过加载CSS来设置对应的CSS自定义属性实现覆盖。

示例（修改默认大字号的值）：
```css
body {
 --wp--preset--font-size--large: <新值>;
}
```

##### 元素伪类选择器

古腾堡编辑器支持伪类选择器 `:hover`、`:focus`、`:focus-visible`、`:visited`、`:active`、`:link`、`:any-link`。

```json
"elements": {
		"link": {
			"color": {
				"text": "绿色"
			},
			":hover": {
				"color": {
					"text": "亮粉色"
				}
			}
		}
	}
```

#### 样式变体

区块可以拥有“样式变体”，具体定义参见[block.json规范](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#styles-optional)。主题开发者可以通过`theme.json`文件为已存在的样式变体定义样式属性。未注册样式变体的样式配置将被忽略。

需注意：变体是“区块概念”——仅当与区块绑定时才存在。`theme.json`规范遵循这一特性，只允许在区块层级而非顶层配置`variations`。特别需要强调的是，只有通过区块`block.json`文件或服务端`register_block_style`注册的变体，才会被视作`theme.json`样式配置中的“已注册变体”。

例如，以下是为`core/quote`区块现有`plain`变体定义样式的方式：

```json
{
	"version": 3,
	"styles": {
		"blocks": {
			"core/quote": {
				"variations": {
					"plain": {
						"color": {
							"background": "红色"
						}
					}
				}
			}
		}
	}
}
```

最终输出的CSS为：

```css
.wp-block-quote.is-style-plain {
	background-color: red;
}
```

多个区块类型也可以共享相同的变体样式。推荐以下两种定义共享样式的方法：

1. `theme.json`分部文件
2. 通过`register_block_style`编程注册

##### 变体Theme.json分部文件

与主题样式变体分部文件类似，区块样式变体分部文件也存放在主题的`/styles`目录中。但通过顶层属性`blockTypes`与主题样式变体进行区分。`blockTypes`属性是一个数组，包含已注册该区块样式变体的所有区块类型。

此外，通过`slug`属性可确保不同来源定义的区块样式变体保持一致性，并将可翻译的`title`属性与`slug`解耦。

以下是一个`theme.json`分部文件示例，为Group、Columns和Media & Text区块类型定义“变体A”区块样式：

```json
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"title": "变体A",
	"slug": "variation-a",
	"blockTypes": [ "core/group", "core/columns", "core/media-text" ],
	"styles": {
		"color": {
			"background": "#eed8d3",
			"text": "#201819"
		},
		"elements": {
			"heading": {
				"color": {
					"text": "#201819"
				}
			}
		},
		"blocks": {
			"core/group": {
				"color": {
					"background": "#825f58",
					"text": "#eed8d3"
				},
				"elements": {
					"heading": {
						"color": {
							"text": "#eed8d3"
						}
					}
				}
			}
		}
	}
}
```

##### 编程注册变体样式

除了使用`theme.json`分部文件，您还可以在通过`register_block_style`注册变体时同步注册样式。该方法通过为区块数组注册区块样式，并在`style_data`参数中传入“样式对象”实现。

以下示例为Group和Columns区块注册“绿色”变体。注意通过`style_data`传递的样式对象结构与`theme.json`分部文件中的`styles`属性结构一致。

```php
register_block_style(
    array( 'core/group', 'core/columns' ),
    array(
        'name'       => 'green',
        'label'      => __( '绿色' ),
        'style_data' => array(
            'color'    => array(
                'background' => '#4f6f52',
                'text'       => '#d2e3c8',
            ),
            'blocks'   => array(
                'core/group' => array(
                    'color' => array(
                        'background' => '#739072',
                        'text'       => '#e3eedd',
                    ),
                ),
            ),
            'elements' => array(
                'link'   => array(
                    'color'  => array(
                        'text' => '#ead196',
                    ),
                    ':hover' => array(
                        'color' => array(
                            'text' => '#ebd9b4',
                        ),
                    ),
                ),
            ),
        ),
    )
);
```

### 顶层样式

位于顶层的样式将使用 `body` 选择器进行注册。

{% codetabs %}
{% Input %}

```json
{
	"version": 3,
	"styles": {
		"color": {
			"text": "var(--wp--preset--color--primary)"
		}
	}
}
```

{% Output %}

```css
body {
	color: var( --wp--preset--color--primary );
}
```

{% end %}
### 区块样式

位于区块内的样式将使用区块选择器进行注册。

默认情况下，区块选择器会根据其名称生成，例如 `.wp-block-<不含命名空间的区块名称>`。例如，`core/group` 区块对应 `.wp-block-group`。某些区块可以选择退出此默认行为，只需在其 `block.json` 文件的 `supports` 部分通过 `__experimentalSelector` 键明确指定要使用的选择器即可。需要注意的是，区块必须在服务端注册，样式引擎才能使用 `__experimentalSelector` 字段。

{% codetabs %}
{% Input %}

```json
{
	"version": 3,
	"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)"
				}
			}
		}
	}
}
```

{% Output %}

```css
body {
	color: var( --wp--preset--color--primary );
}
p { /* core/paragraph 区块选择退出默认行为，使用 p 作为选择器。 */
	color: var( --wp--preset--color--secondary );
}
.wp-block-group {
	color: var( --wp--preset--color--tertiary );
}
```
{% end %}

#### 引用样式

区块可以通过引用根层级样式来进行样式设置。此功能由 Gutenberg 支持。
如果使用 `styles.color.background` 为根层级注册背景颜色：

```JSON
"styles": {
		"color": {
			"background": "var(--wp--preset--color--primary)"
		}
	}
```

你可以使用 `ref: "styles.color.background"` 来为区块复用该样式：

```JSON
{
	"color": {
		"text": { "ref": "styles.color.background" }
	}
}
```

#### 元素样式

除了顶层样式和区块层级样式外，还有一种元素的概念，可以在两个地方使用。它们是一个封闭集合：

Gutenberg 支持的：

- `button`：映射到 `wp-element-button` CSS 类。同时为了向后兼容，也映射到 `wp-block-button__link`。
- `caption`：映射到 `.wp-element-caption, .wp-block-audio figcaption, .wp-block-embed figcaption, .wp-block-gallery figcaption, .wp-block-image figcaption, .wp-block-table figcaption, .wp-block-video figcaption` CSS 类。
- `heading`：映射到所有标题，即 `h1 到 h6` CSS 选择器。

WordPress 支持的：

- `h1`：映射到 `h1` CSS 选择器。
- `h2`：映射到 `h2` CSS 选择器。
- `h3`：映射到 `h3` CSS 选择器。
- `h4`：映射到 `h4` CSS 选择器。
- `h5`：映射到 `h5` CSS 选择器。
- `h6`：映射到 `h6` CSS 选择器。
- `link`：映射到 `a` CSS 选择器。

如果在顶层找到元素样式，将使用元素选择器。如果在区块内找到，使用的选择器将是该元素附加到对应区块的选择器。

{% codetabs %}
{% Input %}

```json
{
	"version": 3,
	"styles": {
		"typography": {
			"fontSize": "var(--wp--preset--font-size--normal)"
		},
		"elements": {
			"h1": {
				"typography": {
					"fontSize": "var(--wp--preset--font-size--huge)"
				}
			},
			"h2": {
				"typography": {
					"fontSize": "var(--wp--preset--font-size--big)"
				}
			},
			"h3": {
				"typography": {
					"fontSize": "var(--wp--preset--font-size--medium)"
				}
			}
		},
		"blocks": {
			"core/group": {
				"elements": {
					"h2": {
						"typography": {
							"fontSize": "var(--wp--preset--font-size--small)"
						}
					},
					"h3": {
						"typography": {
							"fontSize": "var(--wp--preset--font-size--smaller)"
						}
					}
				}
			}
		}
	}
}
```

{% Output %}

```css
body {
	font-size: var( --wp--preset--font-size--normal );
}
h1 {
	font-size: var( --wp--preset--font-size--huge );
}
h2 {
	font-size: var( --wp--preset--font-size--big );
}
h3 {
	font-size: var( --wp--preset--font-size--medium );
}
.wp-block-group h2 {
	font-size: var( --wp--preset--font-size--small );
}
.wp-block-group h3 {
	font-size: var( --wp--preset--font-size--smaller );
}
```
{% end %}

### 版本说明

此字段用于描述 `theme.json` 文件的格式规范。最新版本为 WordPress 6.6 推出的[版本 3](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/)。

当需进行破坏性变更时，会发布新版本。这允许主题开发者自主选择何时启用破坏性变更，并将其 theme.json 文件迁移至新格式。

旧版 `theme.json` 均具有向后兼容性，可继续在新版 WordPress 和 Gutenberg 插件中正常使用。但新功能将基于最新版本进行开发。

请参照[版本迁移指南](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-migrations/)了解升级至最新版本的具体操作。

### 设置项

<div class="callout callout-alert">
Gutenberg 插件扩展了 WordPress 5.8 支持的设置项，使其可兼容其他 WordPress 版本。这些扩展功能需经过成熟度测试后才会被移植至核心代码。

下方选项卡分别展示 WordPress 5.8 支持的设置项与 Gutenberg 插件支持的设置项。
</div>

设置项章节采用以下结构：

{% codetabs %}
{% WordPress %}

```json
{
	"version": 3,
	"settings": {
		"border": {
			"radius": false,
			"color": false,
			"style": false,
			"width": false
		},
		"color": {
			"custom": true,
			"customDuotone": true,
			"customGradient": true,
			"duotone": [],
			"gradients": [],
			"link": false,
			"palette": [],
			"text": true,
			"background": true,
			"defaultGradients": true,
			"defaultPalette": true
		},
		"custom": {},
		"layout": {
			"contentSize": "800px",
			"wideSize": "1000px"
		},
		"spacing": {
			"margin": false,
			"padding": false,
			"blockGap": null,
			"units": [ "px", "em", "rem", "vh", "vw" ]
		},
		"typography": {
			"customFontSize": true,
			"lineHeight": false,
			"dropCap": true,
			"fluid": false,
			"fontStyle": true,
			"fontWeight": true,
			"letterSpacing": true,
			"textDecoration": true,
			"textTransform": true,
			"fontSizes": [],
			"fontFamilies": []
		},
		"blocks": {
			"core/paragraph": {
				"color": {},
				"custom": {},
				"layout": {},
				"spacing": {},
				"typography": {}
			},
			"core/heading": {},
			"etc": {}
		}
	}
}
```

{% Gutenberg %}

```json
{
	"version": 3,
	"settings": {
		"appearanceTools": false,
		"border": {
			"color": false,
			"radius": false,
			"style": false,
			"width": false
		},
		"color": {
			"background": true,
			"custom": true,
			"customDuotone": true,
			"customGradient": true,
			"defaultGradients": true,
			"defaultPalette": true,
			"duotone": [],
			"gradients": [],
			"link": false,
			"palette": [],
			"text": true
		},
		"custom": {},
		"dimensions": {
			"aspectRatio": false,
			"minHeight": false,
		},
		"layout": {
			"contentSize": "800px",
			"wideSize": "1000px"
		},
		"spacing": {
			"blockGap": null,
			"margin": false,
			"padding": false,
			"customSpacingSize": true,
			"units": [ "px", "em", "rem", "vh", "vw" ],
			"spacingScale": {
				"operator": "*",
				"increment": 1.5,
				"steps": 7,
				"mediumStep": 1.5,
				"unit": "rem"
			},
			"spacingSizes": []
		},
		"typography": {
			"customFontSize": true,
			"dropCap": true,
			"fluid": false,
			"fontFamilies": [],
			"fontSizes": [],
			"fontStyle": true,
			"fontWeight": true,
			"letterSpacing": true,
			"lineHeight": false,
			"textAlign": true,
			"textColumns": false,
			"textDecoration": true,
			"textTransform": true
		},
		"blocks": {
			"core/paragraph": {
				"border": {},
				"color": {},
				"custom": {},
				"layout": {},
				"spacing": {},
				"typography": {}
			},
			"core/heading": {},
			"etc": {}
		}
	}
}
```
{% end %}

每个区块均可独立配置这些设置项，实现比 `add_theme_support` 更精细的控制粒度。顶层声明的设置项将影响所有区块，除非特定区块对其进行覆盖。这种机制既提供了配置继承性，也支持一次性配置所有区块。

需要注意的是，并非所有设置项都适用于每个区块。设置项章节为主题提供启用/禁用机制，但具体功能支持仍需由区块自行实现。例如，若某区块未实现 `dropCap` 首字下沉功能，则主题无法通过 `theme.json` 为该区块启用此功能。

```
{% end %}

为保持向后兼容性，通过 `add_theme_support` 声明的预设也会生成 CSS 自定义属性。若 `theme.json` 包含任何预设，这些预设将优先于通过 `add_theme_support` 声明的预设。

预设类通过用户操作附加到文章内容。因此引擎会为这些类添加 `!important` 声明，因为用户样式应优先于主题样式。

#### 自定义配置

除了为预设创建 CSS 自定义属性外，`theme.json` 还允许主题创建自定义属性，无需单独排队加载。在 `custom` 字段内声明的任何值都将按以下命名模式转换为 CSS 自定义属性：`--wp--custom--<变量名称>`。

例如：

{% codetabs %}
{% 输入 %}

```json
{
	"version": 3,
	"settings": {
		"custom": {
			"baseFont": 16,
			"lineHeight": {
				"small": 1.2,
				"medium": 1.4,
				"large": 1.8
			}
		},
		"blocks": {
			"core/group": {
				"custom": {
					"baseFont": 32
				}
			}
		}
	}
}
```

{% 输出 %}

```css
body {
	--wp--custom--base-font: 16;
	--wp--custom--line-height--small: 1.2;
	--wp--custom--line-height--medium: 1.4;
	--wp--custom--line-height--large: 1.8;
}
.wp-block-group {
	--wp--custom--base-font: 32;
}
```

{% end %}

请注意，变量名称通过在每个嵌套层级间添加 `--` 来创建，且 `camelCase` 格式的字段会转换为 `kebab-case` 格式。

#### 设置示例

- 仅对段落区块启用自定义颜色：

```json
{
	"version": 3,
	"settings": {
		"color": {
			"custom": false
		},
		"blocks": {
			"core/paragraph": {
				"color": {
					"custom": true
				}
			}
		}
	}
}
```

- 禁用按钮区块的边框圆角：

```json
{
	"version": 3,
	"settings": {
		"blocks": {
			"core/button": {
				"border": {
					"radius": false
				}
			}
		}
	}
}
```

- 为群组区块提供与其他区块不同的调色板：

```json
{
	"version": 3,
	"settings": {
		"color": {
			"palette": [
				{
					"slug": "black",
					"color": "#000000",
					"name": "黑色"
				},
				{
					"slug": "white",
					"color": "#FFFFFF",
					"name": "白色"
				},
				{
					"slug": "red",
					"color": "#FF0000",
					"name": "红色"
				},
				{
					"slug": "green",
					"color": "#00FF00",
					"name": "绿色"
				},
				{
					"slug": "blue",
					"color": "#0000FF",
					"name": "蓝色"
				}
			]
		},
		"blocks": {
			"core/group": {
				"color": {
					"palette": [
						{
							"slug": "black",
							"color": "#000000",
							"name": "黑色"
						},
						{
							"slug": "white",
							"color": "#FFF",
							"name": "白色"
						}
					]
				}
			}
		}
	}
}
```

### 样式

<div class="callout callout-alert">
Gutenberg 插件扩展了 WordPress 5.8 的可用样式，使其可与其他 WordPress 版本兼容，这些样式在移植到核心版本前需经过成熟度验证。

下方标签页分别展示 WordPress 5.8 支持的样式与 Gutenberg 插件支持的样式。
</div>

每个区块通过[区块支持机制](/docs/reference-guides/block-api/block-supports.md)声明其暴露的样式属性。这些支持声明用于在编辑器中自动生成区块的 UI 控件。主题可通过 `theme.json` 为任何区块使用样式属性——但需由主题自行验证这些样式是否能根据区块标记等要素正常生效。

{% codetabs %}
{% WordPress %}

```json
{
	"version": 3,
	"styles": {
		"border": {
			"radius": "value",
			"color": "value",
			"style": "value",
			"width": "value"
		},
		"filter": {
			"duotone": "value"
		},
		"color": {
			"background": "value",
			"gradient": "value",
			"text": "value"
		},
		"spacing": {
			"blockGap": "value",
			"margin": {
				"top": "value",
				"right": "value",
				"bottom": "value",
				"left": "value",
			},
			"padding": {
				"top": "value",
				"right": "value",
				"bottom": "value",
				"left": "value"
			}
		},
		"typography": {
			"fontSize": "value",
			"fontStyle": "value",
			"fontWeight": "value",
			"letterSpacing": "value",
			"lineHeight": "value",
			"textDecoration": "value",
			"textTransform": "value"
		},
		"elements": {
			"link": {
				"border": {},
				"color": {},
				"spacing": {},
				"typography": {}
			},
			"h1": {},
			"h2": {},
			"h3": {},
			"h4": {},
			"h5": {},
			"h6": {}
		},
		"blocks": {
			"core/group": {
				"border": {},
				"color": {},
				"spacing": {},
				"typography": {},
				"elements": {
					"link": {},
					"h1": {},
					"h2": {},
					"h3": {},
					"h4": {},
					"h5": {},
					"h6": {}
				}
			},
			"etc": {}
		}
	}
}
```
{% Gutenberg %}

```json
{
	"version": 3,
	"styles": {
		"border": {
			"color": "value",
			"radius": "value",
			"style": "value",
			"width": "value"
		},
		"color": {
			"background": "value",
			"gradient": "value",
			"text": "value"
		},
		"dimensions": {
			"aspectRatio": "value",
			"minHeight": "value"
		},
		"filter": {
			"duotone": "value"
		},
		"spacing": {
			"blockGap": "value",
			"margin": {
				"top": "value",
				"right": "value",
				"bottom": "value",
				"left": "value"
			},
			"padding": {
				"top": "value",
				"right": "value",
				"bottom": "value",
				"left": "value"
			}
		},
		"typography": {
			"fontFamily": "value",
			"fontSize": "value",
			"fontStyle": "value",
			"fontWeight": "value",
			"letterSpacing": "value",
			"lineHeight": "value",
			"textColumns": "value",
			"textDecoration": "value",
			"textTransform": "value"
		},
		"elements": {
			"link": {
				"border": {},
				"color": {},
				"spacing": {},
				"typography": {}
			},
			"h1": {},
			"h2": {},
			"h3": {},
			"h4": {},
			"h5": {},
			"h6": {},
			"heading": {},
			"button": {},
			"caption": {}
		},
		"blocks": {
			"core/group": {
				"border": {},
				"color": {},
				"dimensions": {},
				"spacing": {},
				"typography": {},
				"elements": {
					"link": {},
					"h1": {},
					"h2": {},
					"h3": {},
					"h4": {},
					"h5": {},
					"h6": {}
				}
			},
			"etc": {}
		}
	}
}
```
{% end %}

### 启用UI控件选项

存在一个特殊的设置属性 `appearanceTools`，它是一个布尔值，默认值为 false。主题可以通过此设置启用以下选项：

- 背景：backgroundImage、backgroundSize
- 边框：color、radius、style、width
- 颜色：link
- 尺寸：aspectRatio、minHeight
- 位置：sticky
- 间距：blockGap、margin、padding
- 排版：lineHeight

#### 与 add_theme_support 的向后兼容性

为了保持向后兼容性，现有的用于配置区块编辑器的 `add_theme_support` 声明已被适配到顶层部分的适当类别中。例如，如果主题使用 `add_theme_support('disable-custom-colors')`，则等同于将 `settings.color.custom` 设置为 `false`。如果 `theme.json` 包含任何设置，这些设置将优先于通过 `add_theme_support` 声明的值。以下是完整的等效关系列表：

| add_theme_support           | theme.json 设置                                             |
| --------------------------- | ------------------------------------------------------------ |
| `custom-line-height`        | 将 `typography.lineHeight` 设置为 `true`。                   |
| `custom-spacing`            | 将 `spacing.padding` 设置为 `true`。                         |
| `custom-units`              | 通过 `spacing.units` 提供单位列表。                          |
| `disable-custom-colors`     | 将 `color.custom` 设置为 `false`。                           |
| `disable-custom-font-sizes` | 将 `typography.customFontSize` 设置为 `false`。              |
| `disable-custom-gradients`  | 将 `color.customGradient` 设置为 `false`。                   |
| `editor-color-palette`      | 通过 `color.palette` 提供颜色列表。                          |
| `editor-font-sizes`         | 通过 `typography.fontSizes` 提供字体大小列表。               |
| `editor-gradient-presets`   | 通过 `color.gradients` 提供渐变列表。                        |
| `editor-spacing-sizes`      | 通过 `spacing.spacingSizes` 提供间距尺寸列表。               |
| `appearance-tools`          | 将 `appearanceTools` 设置为 `true`。                         |
| `border`                    | 将 `border: color, radius, style, width` 设置为 `true`。     |
| `link-color `               | 将 `color.link` 设置为 `true`。                              |

#### 预设

预设是设置部分的一部分。它们是通过某些UI控件向用户显示的值。通过 `theme.json` 定义这些值，引擎可以为主题提供更多功能，例如自动翻译预设名称或排队相应的CSS类和自定义属性。

可以通过 `theme.json` 定义以下预设：

- `color.duotone`：不生成类或自定义属性。
- `color.gradients`：为每个预设值生成一个类和一个自定义属性。
- `color.palette`：
  - 为每个预设值生成3个类：color、background-color 和 border-color。
  - 为每个预设值生成一个自定义属性。
- `spacing.spacingSizes`/`spacing.spacingScale`：为每个预设值生成一个自定义属性。
- `typography.fontSizes`：为每个预设值生成一个类和一个自定义属性。
- `typography.fontFamilies`：为每个预设值生成一个自定义属性。

类和自定义属性的命名规则如下：

- 自定义属性：`--wp--preset--{preset-category}--{preset-slug}`，例如 `--wp--preset--color--black`
- 类：`.has-{preset-slug}-{preset-category}`，例如 `.has-black-color`

{% codetabs %}
{% 输入 %}

```json
{
	"version": 3,
	"settings": {
		"color": {
			"duotone": [
				{
					"colors": [ "#000", "#FFF" ],
					"slug": "black-and-white",
					"name": "Black and White"
				}
			],
			"gradients": [
				{
					"slug": "blush-bordeaux",
					"gradient": "linear-gradient(135deg,rgb(254,205,165) 0%,rgb(254,45,45) 50%,rgb(107,0,62) 100%)",
					"name": "Blush bordeaux"
				},
				{
					"slug": "blush-light-purple",
					"gradient": "linear-gradient(135deg,rgb(255,206,236) 0%,rgb(152,150,240) 100%)",
					"name": "Blush light purple"
				}
			],
			"palette": [
				{
					"slug": "strong-magenta",
					"color": "#a156b4",
					"name": "Strong magenta"
				},
				{
					"slug": "very-dark-grey",
					"color": "rgb(131, 12, 8)",
					"name": "Very dark grey"
				}
			]
		},
		"typography": {
			"fontFamilies": [
				{
					"fontFamily": "-apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Oxygen-Sans,Ubuntu,Cantarell, \"Helvetica Neue\",sans-serif",
					"slug": "system-font",
					"name": "System Font"
				},
				{
					"fontFamily": "Helvetica Neue, Helvetica, Arial, sans-serif",
					"slug": "helvetica-arial",
					"name": "Helvetica or Arial"
				}
			],
			"fontSizes": [
				{
					"slug": "big",
					"size": 32,
					"name": "Big"
				},
				{
					"slug": "x-large",
					"size": 46,
					"name": "Large"
				}
			]
		},
		"spacing": {
			"spacingScale": {
				"operator": "*",
				"increment": 1.5,
				"steps": 7,
				"mediumStep": 1.5,
				"unit": "rem"
			},
			"spacingSizes": [
				{
					"slug": "40",
					"size": "1rem",
					"name": "Small"
				},
				{
					"slug": "50",
					"size": "1.5rem",
					"name": "Medium"
				},
				{
					"slug": "60",
					"size": "2rem",
					"name": "Large"
				}
			]
		},
		"blocks": {
			"core/group": {
				"color": {
					"palette": [
						{
							"slug": "black",
							"color": "#000000",
							"name": "Black"
						},
						{
							"slug": "white",
							"color": "#ffffff",
							"name": "White"
						}
					]
				}
			}
		}
	}
}
```

{% 输出 %}

```css
/* 顶层自定义属性 */
body {
	--wp--preset--color--strong-magenta: #a156b4;
	--wp--preset--color--very-dark-grey: #444;
	--wp--preset--gradient--blush-bordeaux: linear-gradient( 135deg, rgb( 254, 205, 165 ) 0%, rgb( 254, 45, 45 ) 50%, rgb( 107, 0, 62 ) 100% );
	--wp--preset--gradient--blush-light-purple: linear-gradient( 135deg, rgb( 255, 206, 236 ) 0%, rgb( 152, 150, 240 ) 100% );
	--wp--preset--font-size--x-large: 46;
	--wp--preset--font-size--big: 32;
	--wp--preset--font-family--helvetica-arial: Helvetica Neue, Helvetica, Arial, sans-serif;
	--wp--preset--font-family--system: -apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Oxygen-Sans,Ubuntu,Cantarell, \"Helvetica Neue\",sans-serif;
	--wp--preset--spacing--20: 0.44rem;
	--wp--preset--spacing--30: 0.67rem;
	--wp--preset--spacing--40: 1rem;
	--wp--preset--spacing--50: 1.5rem;
	--wp--preset--spacing--60: 2.25rem;
	--wp--preset--spacing--70: 3.38rem;
	--wp--preset--spacing--80: 5.06rem;
}

/* 区块级自定义属性（绑定到群组区块） */
.wp-block-group {
	--wp--preset--color--black: #000000;
	--wp--preset--color--white: #ffffff;
}

/* 顶层类 */
.has-strong-magenta-color { color: #a156b4 !important; }
.has-strong-magenta-background-color { background-color: #a156b4 !important; }
.has-strong-magenta-border-color { border-color: #a156b4 !important; }
.has-very-dark-grey-color { color: #444 !important; }
.has-very-dark-grey-background-color { background-color: #444 !important; }
.has-very-dark-grey-border-color { border-color: #444 !important; }
.has-blush-bordeaux-background { background: linear-gradient( 135deg, rgb( 254, 205, 165 ) 0%, rgb( 254, 45, 45 ) 50%, rgb( 107, 0, 62 ) 100% ) !important; }
.has-blush-light-purple-background { background: linear-gradient( 135deg, rgb( 255, 206, 236 ) 0%, rgb( 152, 150, 240 ) 100% ) !important; }
.has-big-font-size { font-size: 32; }
.has-normal-font-size { font-size: 16; }

/* 区块级类（绑定到群组区块） */
.wp-block-group.has-black-color { color: #a156b4 !important; }
.wp-block-group.has-black-background-color { background-color: #a156b4 !important; }
.wp-block-group.has-black-border-color { border-color: #a156b4 !important; }
.wp-block-group.has-white-color { color: #444 !important; }
.wp-block-group.has-white-background-color { background-color: #444 !important; }
.wp-block-group.has-white-border-color { border-color: #444 !important; }
```