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