2551654928/gutenbergdocs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
unknown
2025-10-22 01:33:45 +08:00
commit 2080fa3878
251 changed files with 47081 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
reference-guides/theme-json-reference/README.md Normal file
View File

@@ -0,0 +1,11 @@
# Theme.json 参考文档
本参考指南列出了 theme.json 架构中定义的设置与样式属性。如需了解如何在主题中使用 theme.json 文件的示例及指南，请参阅 [theme.json 使用指南](/docs/how-to-guides/themes/global-settings-and-styles.md)。
- [版本 3（最新版）](/docs/reference-guides/theme-json-reference/theme-json-living.md)
## 历史版本
- [迁移至新版 Theme.json](/docs/reference-guides/theme-json-reference/theme-json-migrations.md)
- [版本 1](/docs/reference-guides/theme-json-reference/theme-json-v1.md)
- [版本 2](/docs/reference-guides/theme-json-reference/theme-json-v2.md)

57
reference-guides/theme-json-reference/styles-versions.md Normal file
View File

@@ -0,0 +1,57 @@
# 可用样式选项
新的样式选项会定期集成到 theme.json 中。要随时了解通过 theme.json 或样式编辑器可用的样式选项可能具有挑战性。为明确说明，下表列出了每个 theme.json 样式选项可用的 WordPress 版本，以及相应控件添加到用户界面以便通过样式编辑器管理该样式的时间。
## 样式键值
| 键值 | theme.json 起始版本 | 样式编辑器起始版本 |
| --- | :---: | :---: |
| `color.gradient` | 5.8 | 5.9 |
| `color.background` | 5.8 | 5.9 |
| `color.text` | 5.8 | 5.9 |
| `border.color` | 5.9 | 5.9 |
| `border.width` | 5.9 | 5.9 |
| `border.style` | 5.9 | 5.9 |
| `border.radius` | 5.8 | 5.9 |
| `border.radius.topLeft` | 5.9 | 5.9 |
| `border.radius.topRight` | 5.9 | 5.9 |
| `border.radius.bottomLeft` | 5.9 | 5.9 |
| `border.radius.bottomRight` | 5.9 | 5.9 |
| `border.top.color` | 6.1 | 6.1 |
| `border.top.width` | 6.1 | 6.1 |
| `border.top.style` | 6.1 | 6.1 |
| `border.right.color` | 6.1 | 6.1 |
| `border.right.width` | 6.1 | 6.1 |
| `border.right.style` | 6.1 | 6.1 |
| `border.bottom.color` | 6.1 | 6.1 |
| `border.bottom.width` | 6.1 | 6.1 |
| `border.bottom.style` | 6.1 | 6.1 |
| `border.left.color` | 6.1 | 6.1 |
| `border.left.width` | 6.1 | 6.1 |
| `border.left.style` | 6.1 | 6.1 |
| `typography.fontFamily` | 5.9 | 5.9 |
| `typography.fontSize` | 5.8 | 5.9 |
| `typography.fontStyle` | 5.9 | 5.9 |
| `typography.fontWeight` | 5.9 | 5.9 |
| `typography.letterSpacing` | 5.9 | 5.9 |
| `typography.lineHeight` | 5.8 | 5.9 |
| `typography.textDecoration` | 5.9 | 6.2 |
| `typography.textTransform` | 5.9 | 6.0 |
| `spacing.padding` | 5.9 | 5.9 |
| `spacing.padding.top` | 5.8 | 5.9 |
| `spacing.padding.right` | 5.8 | 5.9 |
| `spacing.padding.left` | 5.8 | 5.9 |
| `spacing.padding.bottom` | 5.8 | 5.9 |
| `spacing.margin` | 5.9 | 5.9 |
| `spacing.margin.top` | 5.8 | 5.9 |
| `spacing.margin.right` | 5.8 | 5.9 |
| `spacing.margin.left` | 5.8 | 5.9 |
| `spacing.margin.bottom` | 5.8 | 5.9 |
| `spacing.blockGap` | 5.9 | 5.9 |
| `dimensions.minHeight` | 6.2 | 不适用 |
| `outline.color` | 6.2 | 不适用 |
| `outline.offset` | 6.2 | 不适用 |
| `outline.style` | 6.2 | 不适用 |
| `outline.width` | 6.2 | 不适用 |
| `filter.duotone` | 5.9 | 不适用 |
| `shadow` | 6.1 | 6.2 |

361
reference-guides/theme-json-reference/theme-json-living.md Normal file
View File

@@ -0,0 +1,361 @@
## 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 | 字体家族选择器的字体家族预设。 | `[ { 名称, 别名, 字体家族, 字体文件 } ]` | |
---

110
reference-guides/theme-json-reference/theme-json-migrations.md Normal file
View File

@@ -0,0 +1,110 @@
# 迁移 Theme.json 至新版指南
本文档记录了不同版本 `theme.json` 之间的变更内容及升级方式。旧版本将持续获得支持，但建议升级至新版以获得持续的功能更新。
## 从 v1 迁移至 v2
升级至 v2 版本可启用新功能，并对旧功能命名进行统一优化。
### 迁移步骤：
1. 将 `version` 字段更新为 `2`
2. 检查并重命名已变更的属性（详见下表）
请参考[版本发布说明](https://make.wordpress.org/core/2022/01/08/updates-for-settings-styles-and-theme-json/)及[v1/v2版本参考文档](/docs/reference-guides/theme-json-reference/README.md)。
### 属性重命名对照表
| v1 版本 | v2 版本 |
| -------------------------------------- | -------------------------------- |
| `settings.border.customRadius` | `settings.border.radius` |
| `settings.spacing.customMargin` | `settings.spacing.margin` |
| `settings.spacing.customPadding` | `settings.spacing.padding` |
| `settings.typography.customLineHeight` | `settings.typography.lineHeight` |
### 新增属性
新增顶层属性：`customTemplates`、`templateParts`
配置项(sections)新增：
- `settings.appearanceTools`
- `settings.border.color`
- `settings.border.style`
- `settings.border.width`
- `settings.color.background`
- `settings.color.defaultGradients`
- `settings.color.defaultPalette`
- `settings.color.text`
- `settings.spacing.blockGap`
- `settings.typography.fontFamilies`
- `settings.typography.fontStyle`
- `settings.typography.fontWeight`
- `settings.typography.letterSpacing`
- `settings.typography.textColumns`
- `settings.typography.textDecoration`
- `settings.typography.textTransform`
样式项(styles)新增：
- `styles.border.color`
- `styles.border.style`
- `styles.border.width`
- `styles.filter.duotone`
- `styles.spacing.blockGap`
- `styles.typography.fontFamily`
- `styles.typography.fontStyle`
- `styles.typography.fontWeight`
- `styles.typography.letterSpacing`
- `styles.typography.textColumns`
- `styles.typography.textDecoration`
- `styles.typography.textTransform`
### 属性值变更
核心默认字体尺寸(`settings.typography.fontSizes`)已更新：移除了常规尺寸(Normal)与超大尺寸(Huge)（对应标识符为`normal`和`huge`），新增特大尺寸(Extra Large，标识符为`x-large`)。当界面控件显示核心默认值时，常规尺寸与超大尺寸将不再出现。但为确保现有内容正常显示，其CSS类及CSS自定义属性仍会保留。
## 从 v2 迁移至 v3
升级至 v3 版本将对预设默认值进行统一性优化。
### 迁移步骤：
1. 将 `version` 字段更新为 `3`
2. 根据下文说明配置变更的默认值
### 默认值变更
#### `settings.typography.defaultFontSizes`
在 theme.json v2 中，默认字体尺寸仅在主题未定义尺寸时显示。若主题提供的字体尺寸与默认标识符相同，则会始终覆盖默认值。
默认字体尺寸标识符包括：`small`、`medium`、`large`、`x-large`、`xx-large`
新增的 `defaultFontSizes` 选项可控制默认字体尺寸的显示与覆盖行为：
- 设为 `true` 时显示默认字体尺寸并禁止主题覆盖
- 设为 `false` 时隐藏默认字体尺寸并允许主题使用默认标识符
升级至 v3 后该值默认为 `true`，此举是为了与 `settings.color.defaultPalette` 等其他默认选项保持一致性，但与 v2 行为存在差异。
若需在 v3 中保持 v2 行为：
* 未定义任何 `fontSizes` 时，可保留 `defaultFontSizes` 或设为 `true`
* 已定义部分 `fontSizes` 时，需将 `defaultFontSizes` 设为 `false`
#### `settings.spacing.defaultSpacingSizes`
在 theme.json v2 中，存在两种设置主题级间距尺寸的方式：`settings.spacing.spacingSizes` 与 `settings.spacing.spacingScale`。若同时设置两者，仅会采用 `spacingSizes` 的数值。设置任一选项都会完全替换WordPress提供的默认间距尺寸。
WordPress提供的默认间距尺寸标识符包括：`20`、`30`、`40`、`50`、`60`、`70`、`80`
新增的 `defaultSpacingSizes` 选项可控制默认间距尺寸的显示与覆盖行为：
- 设为 `true` 时显示默认间距尺寸并禁止主题覆盖
- 设为 `false` 时隐藏默认间距尺寸并允许主题使用默认标识符
升级至 v3 后该值默认为 `true`，此举是为了与 `settings.color.defaultPalette` 等其他默认选项保持一致性，但与 v2 行为存在差异。
此外在 v3 中可同时设置 `spacingSizes` 与 `spacingScale`。当 `spacingSizes` 中定义的预设标识符与 `spacingScale` 生成的预设相同时，前者将覆盖后者。
若需在 v3 中保持 v2 行为：
* 未定义任何 `spacingSizes` 预设或 `spacingScale` 配置时，可保留 `defaultSpacingSizes` 或设为 `true`
* 若曾通过设置 `spacingScale` 为 `{ "steps": 0 }` 禁用默认间距尺寸，需移除 `spacingScale` 配置并将 `defaultSpacingSizes` 设为 `false`
* 若仅通过 `spacingScale` 或 `spacingSizes` 之一定义预设，需将 `defaultSpacingSizes` 设为 `false`
* 若曾同时设置 `spacingScale` 与 `spacingSizes`，需移除 `spacingSizes` 配置并将 `defaultSpacingSizes` 设为 `false`

135
reference-guides/theme-json-reference/theme-json-v1.md Normal file
View File

@@ -0,0 +1,135 @@
# Theme.json 版本1参考文档
> 本文档是 `theme.json` **版本1** 的技术规范。该版本适用于 WordPress 5.8 及以上版本。
<div class="callout callout-alert">
Theme.json 版本2 已随 WordPress 5.9 发布。WordPress 将继续支持 theme.json 版本1，但新功能将仅添加到[新版本文档](/docs/reference-guides/theme-json-reference/theme-json-living.md)中。
当您准备升级时，请参阅 [theme.json 迁移指南](/docs/reference-guides/theme-json-reference/theme-json-migrations.md#migrating-from-v1-to-v2)了解更新至最新版本的详细信息。
</div>
本参考指南列出了 `theme.json` 架构中定义的设置项和样式属性。关于如何在主题中使用 `theme.json` 文件的示例与指导，请参阅 [theme.json 使用指南](/docs/how-to-guides/themes/global-settings-and-styles.md)。
## JSON 架构
版本1的最终架构文件位于：`https://schemas.wp.org/wp/5.8/theme.json`
各 WordPress 版本对应的 Theme.json 架构文件路径为：`https://schemas.wp.org/wp/{{version}}/theme.json`。例如 WordPress 5.8 的架构文件地址为：`https://schemas.wp.org/wp/5.8/theme.json`。
关于如何在编辑器中运用 JSON 架构，请参阅[使用 theme.json 进行开发](/docs/how-to-guides/themes/global-settings-and-styles.md#developing-with-themejson)。
## 设置项
### 边框
与边框相关的设置。
| 属性 | 类型 | 默认值 | 参数 |
| ------------- | ------- | ------- | ---- |
| customRadius | boolean | false | |
---
### 颜色
与颜色相关的设置。
| 属性 | 类型 | 默认值 | 参数 |
| ---------------- | ------- | ------- | -------------------- |
| custom | boolean | true | |
| customDuotone | boolean | true | |
| customGradient | boolean | true | |
| duotone | array | | colors, name, slug |
| gradients | array | | gradient, name, slug |
| link | boolean | false | |
| palette | array | | color, name, slug |
---
### 布局
与布局相关的设置。
| 属性 | 类型 | 默认值 | 参数 |
| ------------ | ------ | ------ | ---- |
| contentSize | string | | |
| wideSize | string | | |
---
### 间距
与间距相关的设置。
| 属性 | 类型 | 默认值 | 参数 |
| --------------- | ------- | ------------------ | ---- |
| customMargin | boolean | false | |
| customPadding | boolean | false | |
| units | array | px,em,rem,vh,vw,% | |
---
### 排版
与排版相关的设置。
| 属性 | 类型 | 默认值 | 参数 |
| ------------------ | ------- | ------- | --------------- |
| customFontSize | boolean | true | |
| customLineHeight | boolean | false | |
| dropCap | boolean | true | |
| fontSizes | array | | name, size, slug |
---
### 自定义
生成格式为 `--wp--custom--{键名}--{嵌套键名}: {值};` 的自定义 CSS 属性。`驼峰式命名`的键名将转换为`短横线命名法`以遵循 CSS 属性命名规范。不同层级的键名通过 `--` 分隔，因此键名中不应包含 `--`。
---
## 样式
### 边框
边框样式。
| 属性 | 类型 | 参数 |
| ------ | ------ | ---- |
| radius | string | |
---
### 颜色
颜色样式。
| 属性 | 类型 | 参数 |
| ----------- | ------ | ---- |
| background | string | |
| gradient | string | |
| text | string | |
---
### 间距
间距样式。
| 属性 | 类型 | 参数 |
| ------- | ------ | ----------------------- |
| margin | object | bottom, left, right, top |
| padding | object | bottom, left, right, top |
---
### 排版
排版样式。
| 属性 | 类型 | 参数 |
| ------------ | ------ | ---- |
| fontSize | string | |
| lineHeight | string | |

331
reference-guides/theme-json-reference/theme-json-v2.md Normal file
View File

@@ -0,0 +1,331 @@
## 模板部件
用于定义在部件文件夹中的模板部件的附加元数据。
类型：`对象`
| 属性 | 描述 | 类型 |
|----------|--------------------------------------------------------------|----------|
| 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 |