## customTemplates（自定义模板）

用于存放模板文件夹中自定义模板的附加元数据。

| 属性 | 说明 | 类型 |
| -------- | ----------- | ---- |
| name | 模板文件名称（不含扩展名），位于模板文件夹内。 | `字符串` |
| title | 模板标题（支持翻译）。 | `字符串` |
| postTypes | 可使用此自定义模板的文章类型列表。 | `[ 字符串 ]` |

## templateParts（模板部件）

用于存放部件文件夹中模板部件的附加元数据。

| 属性 | 说明 | 类型 |
| -------- | ----------- | ---- |
| name | 模板文件名称（不含扩展名），位于部件文件夹内。 | `字符串` |
| title | 模板标题（支持翻译）。 | `字符串` |
| area | 模板部件的适用区域。当设置为`header`或`footer`时，将使用对应的区块变体。 | `字符串` |

## patterns（模式）

从模式目录注册的模式标识数组。

类型：`[ 字符串 ]`

<!-- END TOKEN Autogenerated - DO NOT EDIT -->

# Theme.json 第 3 版参考文档（最新版）

> 本文档是 `theme.json` **第 3 版**的动态技术规范。该版本适用于 WordPress 6.6 及以上版本，以及最新的 Gutenberg 插件。
>
> 您可能对以下相关文档感兴趣：
> - [theme.json v1](/docs/reference-guides/theme-json-reference/theme-json-v1.md) 技术规范
> - [theme.json v2](/docs/reference-guides/theme-json-reference/theme-json-v2.md) 技术规范
> - [从旧版 theme.json 迁移的参考指南](/docs/reference-guides/theme-json-reference/theme-json-migrations.md)

本参考指南列出了 `theme.json` 架构中定义的设置项和样式属性。关于如何在主题中使用 `theme.json` 文件的示例与指南，请参阅 [theme.json 使用指南](/docs/how-to-guides/themes/global-settings-and-styles.md)。

## JSON 架构

本文档根据 theme.json 的 JSON 架构生成。

包含 Gutenberg 插件所有最新更改的第 3 版最新架构可在 <code>https://schemas.wp.org/trunk/theme.json</code> 获取。

各 WordPress 版本对应的 Theme.json 架构可在 <code>https://schemas.wp.org/wp/{{version}}/theme.json</code> 获取。  
例如，WordPress 5.8 的架构位于 <code>https://schemas.wp.org/wp/5.8/theme.json</code>。

关于如何在编辑器中运用 JSON 架构，请参阅[使用 theme.json 进行开发](/docs/how-to-guides/themes/global-settings-and-styles.md#developing-with-themejson)。

<!-- START TOKEN Autogenerated - DO NOT EDIT -->
## settings

区块编辑器及各独立区块的设置项。包含以下内容：
- 应向用户开放哪些自定义选项
- 默认可供用户使用的颜色、字体大小等
- 样式中使用的 CSS 自定义属性与类名
- 编辑器的默认布局（宽度与可用对齐方式）

### useRootPaddingAwareAlignments

启用根内边距（取自 `styles.spacing.padding` 的值）应用于全宽区块内容而非根区块。

请注意，使用此设置时，`styles.spacing.padding` 必须始终设置为包含独立声明的 `top`、`right`、`bottom`、`left` 值的对象。

**注意：** 仅限顶级属性。不可在区块中使用。

---

### appearanceTools

用于启用以下界面工具的设置：

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

---

### background

与背景相关的设置。

| 属性 | 描述 | 类型 | 默认值 |
| -------- | ----------- | ---- | ------- |
| backgroundImage | 允许用户设置背景图片。 | `boolean` | `false` |
| backgroundSize | 允许用户设置背景图片尺寸相关值，包括尺寸、位置和重复控制。 | `boolean` | `false` |

---

### border

与边框相关的设置。

| 属性 | 描述 | 类型 | 默认值 |
| -------- | ----------- | ---- | ------- |
| color | 允许用户设置自定义边框颜色。 | `boolean` | `false` |
| radius | 允许用户设置自定义边框圆角。 | `boolean` | `false` |
| style | 允许用户设置自定义边框样式。 | `boolean` | `false` |
| width | 允许用户设置自定义边框宽度。 | `boolean` | `false` |
| radiusSizes | 边框圆角选择器的预设圆角尺寸。 | `[ { name, slug, size } ]` |  |

---

### color

与颜色相关的设置。

| 属性 | 描述 | 类型 | 默认值 |
| -------- | ----------- | ---- | ------- |
| background | 允许用户设置背景颜色。 | `boolean` | `true` |
| custom | 允许用户选择自定义颜色。 | `boolean` | `true` |
| customDuotone | 允许用户创建自定义双色调滤镜。 | `boolean` | `true` |
| customGradient | 允许用户创建自定义渐变。 | `boolean` | `true` |
| defaultDuotone | 允许用户从默认双色调滤镜预设中选择滤镜。 | `boolean` | `true` |
| defaultGradients | 允许用户从默认渐变中选择颜色。 | `boolean` | `true` |
| defaultPalette | 允许用户从默认调色板中选择颜色。 | `boolean` | `true` |
| duotone | 双色调选择器的双色调预设。 | `[ { name, slug, colors } ]` |  |
| gradients | 渐变选择器的渐变预设。 | `[ { name, slug, gradient } ]` |  |
| link | 允许用户在区块中设置链接颜色。 | `boolean` | `false` |
| palette | 颜色选择器的调色板预设。 | `[ { name, slug, color } ]` |  |
| text | 允许用户在区块中设置文本颜色。 | `boolean` | `true` |
| heading | 允许用户在区块中设置标题颜色。 | `boolean` | `true` |
| button | 允许用户在区块中设置按钮颜色。 | `boolean` | `true` |
| caption | 允许用户在区块中设置说明文字颜色。 | `boolean` | `true` |

---

### 自定义

生成形式为 `--wp--custom--{键}--{嵌套键}: {值};` 的自定义 CSS 自定义属性。`驼峰式`命名的键会被转换为`短横线命名法`，以遵循 CSS 属性命名规范。不同层级的键之间使用 `--` 分隔，因此键名中不应包含 `--`。

---

## 样式

用于设置 CSS 属性的结构化方式。顶级样式将被添加到 `body` 选择器中。

### 背景

背景样式。

| 属性 | 描述 | 类型 |
| -------- | ----------- | ---- |
| backgroundImage | 设置 `background-image` CSS 属性。 | `string`, `{ ref }`, `{ url }` |
| backgroundPosition | 设置 `background-position` CSS 属性。 | `string`, `{ ref }` |
| backgroundRepeat | 设置 `background-repeat` CSS 属性。 | `string`, `{ ref }` |
| backgroundSize | 设置 `background-size` CSS 属性。 | `string`, `{ ref }` |
| backgroundAttachment | 设置 `background-attachment` CSS 属性。 | `string`, `{ ref }` |

---

### 边框

边框样式。

| 属性 | 描述 | 类型 |
| -------- | ----------- | ---- |
| color | 设置 `border-color` CSS 属性。 | `string`, `{ ref }` |
| radius | 设置 `border-radius` CSS 属性。 | `string`, `{ ref }`, `{ topLeft, topRight, bottomLeft, bottomRight }` |
| style | 设置 `border-style` CSS 属性。 | `string`, `{ ref }` |
| width | 设置 `border-width` CSS 属性。 | `string`, `{ ref }` |
| top |  | `{ color, style, width }` |
| right |  | `{ color, style, width }` |
| bottom |  | `{ color, style, width }` |
| left |  | `{ color, style, width }` |

---

### 颜色

颜色样式。

| 属性 | 描述 | 类型 |
| -------- | ----------- | ---- |
| background | 设置 `background-color` CSS 属性。 | `string`, `{ ref }` |
| gradient | 设置 `background` CSS 属性。 | `string`, `{ ref }` |
| text | 设置 `color` CSS 属性。 | `string`, `{ ref }` |

---

### CSS

设置自定义 CSS，用于应用其他 theme.json 属性未涵盖的样式。

---

### 尺寸

尺寸样式。

| 属性 | 描述 | 类型 |
| -------- | ----------- | ---- |
| aspectRatio | 设置 `aspect-ratio` CSS 属性。 | `string`, `{ ref }` |
| minHeight | 设置 `min-height` CSS 属性。 | `string`, `{ ref }` |

---

### 滤镜

CSS 和 SVG 滤镜样式。

| 属性 | 描述 | 类型 |
| -------- | ----------- | ---- |
| duotone | 设置双色调滤镜。 | `string`, `{ ref }` |

---

### 轮廓

轮廓样式。

| 属性 | 描述 | 类型 |
| -------- | ----------- | ---- |
| color | 设置 `outline-color` CSS 属性。 | `string`, `{ ref }` |
| offset | 设置 `outline-offset` CSS 属性。 | `string`, `{ ref }` |
| style | 设置 `outline-style` CSS 属性。 | `string`, `{ ref }` |
| width | 设置 `outline-width` CSS 属性。 | `string`, `{ ref }` |

---

### 阴影

盒子阴影样式。

---

### 间距

间距样式。

| 属性 | 描述 | 类型 |
| -------- | ----------- | ---- |
| blockGap | 当 settings.spacing.blockGap 为 true 时，设置 `--wp--style--block-gap` CSS 自定义属性。 | `string`, `{ ref }` |
| margin | 外边距样式。 | `{ top, right, bottom, left }` |
| padding | 内边距样式。 | `{ top, right, bottom, left }` |

---

### 排版

排版样式。

| 属性 | 描述 | 类型 |
| -------- | ----------- | ---- |
| fontFamily | 设置 `font-family` CSS 属性。 | `string`, `{ ref }` |
| fontSize | 设置 `font-size` CSS 属性。 | `string`, `{ ref }` |
| fontStyle | 设置 `font-style` CSS 属性。 | `string`, `{ ref }` |
| fontWeight | 设置 `font-weight` CSS 属性。 | `string`, `{ ref }` |
| letterSpacing | 设置 `letter-spacing` CSS 属性。 | `string`, `{ ref }` |
| lineHeight | 设置 `line-height` CSS 属性。 | `string`, `{ ref }` |
| textAlign | 设置 `text-align` CSS 属性。 | `string`, `{ ref }` |
| textColumns | 设置 `column-count` CSS 属性。 | `string`, `{ ref }` |
| textDecoration | 设置 `text-decoration` CSS 属性。 | `string`, `{ ref }` |
| writingMode | 设置 `writing-mode` CSS 属性。 | `string`, `{ ref }` |
| textTransform | 设置 `text-transform` CSS 属性。 | `string`, `{ ref }` |

---

### 尺寸

与尺寸相关的设置。

| 属性 | 描述 | 类型 | 默认值 |
| -------- | ----------- | ---- | ------- |
| aspectRatio | 允许用户设置宽高比。 | `布尔值` | `false` |
| defaultAspectRatios | 允许用户从默认宽高比集合中选择宽高比。 | `布尔值` | `true` |
| aspectRatios | 允许用户为某些区块定义宽高比。 | `[ { 名称, 别名, 比例 } ]` |  |
| minHeight | 允许用户设置自定义最小高度。 | `布尔值` | `false` |

---

### 布局

与布局相关的设置。

| 属性 | 描述 | 类型 | 默认值 |
| -------- | ----------- | ---- | ------- |
| contentSize | 设置内容的最大宽度。 | `字符串` |  |
| wideSize | 设置宽内容（`.alignwide`）的最大宽度。在计算流体字体大小时也用作最大视口。 | `字符串` |  |
| allowEditing | 禁用布局用户界面控件。 | `布尔值` | `true` |
| allowCustomContentAndWideSize | 启用或禁用自定义内容和宽尺寸控件。 | `布尔值` | `true` |

---

### 灯箱

与灯箱相关的设置。

| 属性 | 描述 | 类型 | 默认值 |
| -------- | ----------- | ---- | ------- |
| enabled | 定义灯箱是否启用。 | `布尔值` |  |
| allowEditing | 定义是否在区块编辑器中显示灯箱用户界面。如果设置为 `false`，用户将无法在区块编辑器中更改灯箱设置。 | `布尔值` |  |

---

### 位置

与位置相关的设置。

| 属性 | 描述 | 类型 | 默认值 |
| -------- | ----------- | ---- | ------- |
| sticky | 允许用户设置粘性位置。 | `布尔值` | `false` |

---

### 阴影

与阴影相关的设置。

| 属性 | 描述 | 类型 | 默认值 |
| -------- | ----------- | ---- | ------- |
| defaultPresets | 允许用户从默认阴影预设中选择阴影。 | `布尔值` | `true` |
| presets | 阴影选择器的阴影预设。 | `[ { 名称, 别名, 阴影 } ]` |  |

---

### 间距

与间距相关的设置。

| 属性 | 描述 | 类型 | 默认值 |
| -------- | ----------- | ---- | ------- |
| blockGap | 启用从 `styles.spacing.blockGap` 生成 `--wp--style--block-gap`。 | `布尔值`, `null` | `null` |
| margin | 允许用户设置自定义外边距。 | `布尔值` | `false` |
| padding | 允许用户设置自定义内边距。 | `布尔值` | `false` |
| units | 用户可用于间距值的单位列表。 | `[ 字符串 ]` | `["px","em","rem","vh","vw","%"]` |
| customSpacingSize | 允许用户设置自定义空间大小。 | `布尔值` | `true` |
| defaultSpacingSizes | 允许用户从默认空间大小预设中选择空间大小。 | `布尔值` | `true` |
| spacingSizes | 空间大小选择器的空间大小预设。 | `[ { 名称, 别名, 大小 } ]` |  |
| spacingScale | 自动为空间大小选择器生成空间大小预设的设置。 | `{ 运算符, 增量, 步数, 中等步数, 单位 }` |  |

---

### 排版

与排版相关的设置。

| 属性 | 描述 | 类型 | 默认值 |
| -------- | ----------- | ---- | ------- |
| defaultFontSizes | 允许用户从默认字体大小预设中选择字体大小。 | `布尔值` | `true` |
| customFontSize | 允许用户设置自定义字体大小。 | `布尔值` | `true` |
| fontStyle | 允许用户设置自定义字体样式。 | `布尔值` | `true` |
| fontWeight | 允许用户设置自定义字体粗细。 | `布尔值` | `true` |
| fluid | 启用流体排版，并允许用户设置全局流体排版参数。 | `布尔值`, `{ 最小字体大小, 最大视口宽度, 最小视口宽度 }` | `false` |
| letterSpacing | 允许用户设置自定义字间距。 | `布尔值` | `true` |
| lineHeight | 允许用户设置自定义行高。 | `布尔值` | `false` |
| textAlign | 允许用户设置文本对齐方式。 | `布尔值` | `true` |
| textColumns | 允许用户设置文本列数。 | `布尔值` | `false` |
| textDecoration | 允许用户设置自定义文本装饰。 | `布尔值` | `true` |
| writingMode | 允许用户设置书写模式。 | `布尔值` | `false` |
| textTransform | 允许用户设置自定义文本变换。 | `布尔值` | `true` |
| dropCap | 启用首字下沉。 | `布尔值` | `true` |
| fontSizes | 字体大小选择器的字体大小预设。 | `[ { 名称, 别名, 大小, 流体 } ]` |  |
| fontFamilies | 字体家族选择器的字体家族预设。 | `[ { 名称, 别名, 字体家族, 字体文件 } ]` |  |

---