## 模板部件

用于定义在部件文件夹中的模板部件的附加元数据。

类型：`对象`

| 属性     | 描述                                                         | 类型     |
|----------|--------------------------------------------------------------|----------|
| name     | 模板在部件文件夹中的文件名（不含扩展名）。                    | 字符串   |
| title    | 模板的标题，支持翻译。                                        | 字符串   |
| area     | 模板部件被用于的区域。针对 `header` 和 `footer` 值存在区块变体，当区域设置为其中之一时，将使用对应的区块变体。 | 字符串   |

## 模式

一组从模式目录注册的模式别名。

类型：`数组`

# Theme.json 版本 2 参考文档

> 本文档是 `theme.json` **版本 2** 的规范说明。该版本适用于 WordPress 5.9 及以上版本。

<div class="callout callout-alert">

Theme.json 版本 3 已随 WordPress 6.6 发布。WordPress 将继续支持 theme.json 版本 2，但新功能将仅添加到[新版本](/docs/reference-guides/theme-json-reference/theme-json-living.md)中。

当您准备升级时，请参阅 [theme.json 迁移指南](/docs/reference-guides/theme-json-reference/theme-json-migrations.md#migrating-from-v2-to-v3)了解更新至最新版本的详细信息。

</div>

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

## JSON 架构

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

版本 2 的最新架构可在 `https://schemas.wp.org/wp/6.5/theme.json` 获取。

各 WordPress 版本对应的 Theme.json 架构可通过 `https://schemas.wp.org/wp/{{version}}/theme.json` 获取。例如，WordPress 5.9 的架构位于 `https://schemas.wp.org/wp/5.9/theme.json`。

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

## 设置项

### appearanceTools

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

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

---

### useRootPaddingAwareAlignments

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

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

---

### border

与边框相关的设置。

| 属性 | 类型 | 默认值 | 参数 |
| --- | --- | --- | --- |
| color | boolean | false |  |
| radius | boolean | false |  |
| style | boolean | false |  |
| width | boolean | false |  |

---

### shadow

与阴影相关的设置。

| 属性 | 类型 | 默认值 | 参数 |
| --- | --- | --- | --- |
| defaultPresets | boolean | true |  |
| presets | array |  | name、shadow、slug |

---

### color

与颜色相关的设置。

| 属性 | 类型 | 默认值 | 参数 |
| --- | --- | --- | --- |
| background | boolean | true |  |
| custom | boolean | true |  |
| customDuotone | boolean | true |  |
| customGradient | boolean | true |  |
| defaultDuotone | boolean | true |  |
| defaultGradients | boolean | true |  |
| defaultPalette | boolean | true |  |
| duotone | array |  | colors、name、slug |
| gradients | array |  | gradient、name、slug |
| link | boolean | false |  |
| palette | array |  | color、name、slug |
| text | boolean | true |  |
| heading | boolean | true |  |
| button | boolean | true |  |

---

### background

与背景相关的设置。

| 属性 | 类型 | 默认值 | 参数 |
| --- | --- | --- | --- |
| backgroundImage | boolean | false |  |

---

### dimensions

与尺寸相关的设置。

| 属性 | 类型 | 默认值 | 参数 |
| --- | --- | --- | --- |
| aspectRatio | boolean | false |  |
| minHeight | boolean | false |  |

---

### layout

与布局相关的设置。

| 属性 | 类型 | 默认值 | 参数 |
| --- | --- | --- | --- |
| contentSize | string |  |  |
| wideSize | string |  |  |
| allowEditing | boolean | true |  |
| allowCustomContentAndWideSize | boolean | true |  |

---

### lightbox

与灯箱效果相关的设置。

| 属性 | 类型 | 默认值 | 参数 |
| --- | --- | --- | --- |
| enabled | boolean |  |  |
| allowEditing | boolean |  |  |

---

### 定位

与定位相关的设置。

| 属性    | 类型    | 默认值 | 参数   |
| ------- | ------- | ------ | ------ |
| sticky  | boolean | false  |        |

---

### 间距

与间距相关的设置。

| 属性              | 类型          | 默认值                | 参数               |
| ----------------- | ------------- | --------------------- | ------------------ |
| blockGap          | boolean, null | null                  |                    |
| margin            | boolean       | false                 |                    |
| padding           | boolean       | false                 |                    |
| units             | array         | px,em,rem,vh,vw,%     |                    |
| customSpacingSize | boolean       | true                  |                    |
| spacingSizes      | array         |                       | name, size, slug   |
| spacingScale      | object        |                       |                    |

---

### 排版

与排版相关的设置。

| 属性             | 类型          | 默认值 | 参数                                      |
| ---------------- | ------------- | ------ | ----------------------------------------- |
| customFontSize   | boolean       | true   |                                           |
| fontStyle        | boolean       | true   |                                           |
| fontWeight       | boolean       | true   |                                           |
| fluid            | object, boolean | false  | _{maxViewportWidth, minFontSize, minViewportWidth}_ |
| letterSpacing    | boolean       | true   |                                           |
| lineHeight       | boolean       | false  |                                           |
| textColumns      | boolean       | false  |                                           |
| textDecoration   | boolean       | true   |                                           |
| writingMode      | boolean       | false  |                                           |
| textTransform    | boolean       | true   |                                           |
| dropCap          | boolean       | true   |                                           |
| fontSizes        | array         |        | fluid, name, size, slug                   |
| fontFamilies     | array         |        | fontFace, fontFamily, name, slug          |

---

### 自定义

生成形式为 `--wp--custom--{key}--{nested-key}: {value};` 的自定义 CSS 属性。`camelCased` 格式的键会被转换为 `kebab-case` 以遵循 CSS 属性命名规范。不同深度的键之间用 `--` 分隔，因此键名中不应包含 `--`。

---

## 样式

### 边框

边框样式。

| 属性   | 类型          | 参数               |
| ------ | ------------- | ------------------ |
| color  | string, object |                    |
| radius | string, object |                    |
| style  | string, object |                    |
| width  | string, object |                    |
| top    | object        | color, style, width |
| right  | object        | color, style, width |
| bottom | object        | color, style, width |
| left   | object        | color, style, width |

---

### 颜色

颜色样式。

| 属性        | 类型          | 参数 |
| ----------- | ------------- | ---- |
| background  | string, object |      |
| gradient    | string, object |      |
| text        | string, object |      |

---

### 尺寸

尺寸样式。

| 属性          | 类型          | 参数 |
| ------------- | ------------- | ---- |
| aspectRatio   | string, object |      |
| minHeight     | string, object |      |

---

### 间距

间距样式。

| 属性     | 类型          | 参数                     |
| -------- | ------------- | ------------------------ |
| blockGap | string, object |                          |
| margin   | object        | bottom, left, right, top |
| padding  | object        | bottom, left, right, top |

---

### 排版

排版样式。

| 属性           | 类型          | 参数 |
| -------------- | ------------- | ---- |
| fontFamily     | string, object |      |
| fontSize       | string, object |      |
| fontStyle      | string, object |      |
| fontWeight     | string, object |      |
| letterSpacing  | string, object |      |
| lineHeight     | string, object |      |
| textColumns    | string        |      |
| textDecoration | string, object |      |
| writingMode    | string, object |      |
| textTransform  | string, object |      |

---

### 滤镜

CSS 和 SVG 滤镜样式。

| 属性     | 类型          | 参数 |
| -------- | ------------- | ---- |
| duotone  | string, object |      |

---

### 阴影

盒子阴影样式。

---

### 轮廓

轮廓样式。

| 属性   | 类型          | 参数 |
| ------ | ------------- | ---- |
| color  | string, object |      |
| offset | string, object |      |
| style  | string, object |      |
| width  | string, object |      |

---

### CSS

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

---

## 自定义模板

为 templates 文件夹中定义的自定义模板提供额外元数据。

类型：`object`。

| 属性       | 描述                               | 类型   |
| ---------- | ---------------------------------- | ------ |
| name       | 模板在 templates 文件夹中的文件名（不含扩展名）。 | string |
| title      | 模板的标题（可翻译）。             | string |
| postTypes  | 可以使用此自定义模板的文章类型列表。 | array  |