这是 theme.json 的版本 2规范。此版本适用于 WordPress 5.9 或更高版本。
随着 WordPress 6.6 的发布，theme.json 版本 3 也已推出。WordPress 将继续支持 theme.json 版本 2。然而，新功能将仅添加到[新版本](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/)中。
当您准备升级时，请参阅 [theme.json 迁移指南](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-migrations/#migrating-from-v2-to-v3)，了解更新到最新版本的相关信息。
本参考指南列出了在 theme.json 模式中定义的设置和样式属性。有关如何在主题中使用 theme.json 文件的示例和指导，请参阅 theme.json 操作指南。
JSON Schema
本文档是根据 theme.json 的 JSON schema 生成的。
版本 2 的最新 schema 可在 `https://schemas.wp.org/wp/6.5/theme.json` 获取。
每个 WordPress 版本的 theme.json schemas 可在 https://schemas.wp.org/wp/{{version}}/theme.json` 获取。例如，WordPress 5.9 的 schema 可在https://schemas.wp.org/wp/5.9/theme.json` 获取。
请参阅 使用 theme.json 进行开发，了解如何在编辑器中使用 JSON schema。
设置
appearanceTools
启用以下 UI 工具的设置：
- background: backgroundImage, backgroundSize
- border: color, radius, style, width
- color: link
- dimensions: aspectRatio, minHeight
- position: sticky
- spacing: blockGap, margin, padding
- typography: lineHeight
useRootPaddingAwareAlignments
启用根内边距（来自 styles.spacing.padding 的值）应用于全宽块的内容，而不是根块。
请注意，使用此设置时，styles.spacing.padding 应始终设置为对象，并分别声明 top、right、bottom、left 值。
border
与边框相关的设置。
| 属性 | 类型 | 默认值 | Props |
|---|---|---|---|
| color | boolean | false | |
| radius | boolean | false | |
| style | boolean | false | |
| width | boolean | false |
shadow
与阴影相关的设置。
| 属性 | 类型 | 默认值 | Props |
|---|---|---|---|
| defaultPresets | boolean | true | |
| presets | array | name, shadow, slug |
color
与颜色相关的设置。
| 属性 | 类型 | 默认值 | Props |
|---|---|---|---|
| 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
与背景相关的设置。
| 属性 | 类型 | 默认值 | Props |
|---|---|---|---|
| backgroundImage | boolean | false |
dimensions
与尺寸相关的设置。
| 属性 | 类型 | 默认值 | Props |
|---|---|---|---|
| aspectRatio | boolean | false | |
| minHeight | boolean | false |
layout
与布局相关的设置。
| 属性 | 类型 | 默认值 | Props |
|---|---|---|---|
| contentSize | string | ||
| wideSize | string | ||
| allowEditing | boolean | true | |
| allowCustomContentAndWideSize | boolean | true |
lightbox
与灯箱相关的设置。
| 属性 | 类型 | 默认值 | Props |
|---|---|---|---|
| enabled | boolean | ||
| allowEditing | boolean |
position
与位置相关的设置。
| 属性 | 类型 | 默认值 | Props |
|---|---|---|---|
| sticky | boolean | false |
spacing
与间距相关的设置。
| 属性 | 类型 | 默认值 | Props |
|---|---|---|---|
| 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 |
typography
与排版相关的设置。
| 属性 | 类型 | 默认值 | Props |
|---|---|---|---|
| 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 |
custom
生成形式为 --wp--custom--{key}--{nested-key}: {value}; 的自定义 CSS 自定义属性。camelCased 键将被转换为 kebab-case 以遵循 CSS 属性命名模式。不同深度级别的键由 -- 分隔，因此键名中不应包含 --。
样式
border
边框样式。
| 属性 | 类型 | Props |
|---|---|---|
| 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 |
color
颜色样式。
| 属性 | 类型 | Props |
|---|---|---|
| background | string, object | |
| gradient | string, object | |
| text | string, object |
dimensions
尺寸样式
| 属性 | 类型 | Props |
|---|---|---|
| aspectRatio | string, object | |
| minHeight | string, object |
spacing
间距样式。
| 属性 | 类型 | Props |
|---|---|---|
| blockGap | string, object | |
| margin | object | bottom, left, right, top |
| padding | object | bottom, left, right, top |
typography
排版样式。
| 属性 | 类型 | Props |
|---|---|---|
| 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 |
filter
CSS 和 SVG 滤镜样式。
| 属性 | 类型 | Props |
|---|---|---|
| duotone | string, object |
shadow
盒阴影样式。
outline
轮廓样式。
| 属性 | 类型 | Props |
|---|---|---|
| color | string, object | |
| offset | string, object | |
| style | string, object | |
| width | string, object |
css
设置自定义 CSS，以应用其他 theme.json 属性未涵盖的样式。
customTemplates
在 templates 文件夹中定义自定义模板的其他元数据。
类型：object。
| 属性 | 描述 | 类型 |
|---|---|---|
| name | templates 文件夹中模板的文件名（不含扩展名）。 | string |
| title | 模板标题，可翻译。 | string |
| postTypes | 可使用此自定义模板的文章类型列表。 | array |
templateParts
在 parts 文件夹中定义的模板部件的其他元数据。
类型：object。
| 属性 | 描述 | 类型 |
|---|---|---|
| name | parts 文件夹中模板部件的文件名（不含扩展名）。 | string |
| title | 模板部件标题，可翻译。 | string |
| area | 该模板部件使用的区域。存在用于 header 和 footer 值的区块变体，当区域设置为其中之一时将使用这些变体。 | string |
Patterns
要从 Pattern Directory 注册的图案 slug 数组。
类型：array。