这是 version 3 的
theme.json的现行规范。此版本适用于 WordPress 6.6 或更高版本，以及最新的 Gutenberg 插件。还有一些相关文件您可能感兴趣：
– theme.json v1 规范，
– theme.json v2 规范，以及
– 从旧版 theme.json 迁移的参考指南。
本参考指南列出了在 theme.json 模式中定义的设置和样式属性。有关如何在主题中使用 theme.json 文件的示例和指导，请参阅 theme.json 使用指南。
JSON Schema
本文档是从 theme.json 的 JSON 模式生成的。
包括来自 Gutenberg 插件的所有最新更改在内的 version 3 的最新模式可在 https://schemas.wp.org/trunk/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 进行开发。
settings
块编辑器和各个块的设置。这些包括：
– 应向用户提供哪些自定义选项。
– 向用户提供的默认颜色、字体大小等。
– 样式中使用的 CSS 自定义属性和类名。
– 编辑器的默认布局（宽度和可用的对齐方式）。
useRootPaddingAwareAlignments
启用根填充（来自 styles.spacing.padding 的值）应用于全宽块的内容，而不是根块。
请注意，使用此设置时，styles.spacing.padding 应始终设置为具有单独声明的 top、right、bottom、left 值的对象。
注意： 仅顶级可用属性。在块中不可用。
appearanceTools
启用以下 UI 工具的设置：
- background: backgroundImage, backgroundSize
- border: color, radius, style, width
- color: link, heading, button, caption
- dimensions: aspectRatio, height, minHeight, minWidth, width
- position: sticky
- spacing: blockGap, margin, padding
- typography: lineHeight
background
与背景相关的设置。
| Property | Description | Type | Default |
|---|---|---|---|
| backgroundImage | 允许用户设置背景图像。 | boolean | false |
| backgroundSize | 允许用户设置与背景图像大小相关的值，包括大小、位置和重复控制。 | boolean | false |
| gradient | 允许用户设置渐变背景。 | boolean | false |
| backgroundClip | 允许用户设置背景裁剪。传递 true 表示所有方法，或者传递一个 CSS 值数组：[“text”, “padding-box”, “border-box”, “content-box”]。 | boolean, [ string ] |
blockVisibility
与块可见性相关的设置。
| Property | Description | Type | Default |
|---|---|---|---|
| allowEditing | 是否可以在编辑器中编辑块可见性。设置为 false 以隐藏块可见性控件。无论此设置如何，保存的块可见性属性都将始终渲染。 | boolean | true |
border
与边框相关的设置。
| Property | Description | Type | Default |
|---|---|---|---|
| color | 允许用户设置自定义边框颜色。 | boolean | false |
| radius | 允许用户设置自定义边框半径。 | boolean | false |
| style | 允许用户设置自定义边框样式。 | boolean | false |
| width | 允许用户设置自定义边框宽度。 | boolean | false |
| radiusSizes | 边框半径选择器的边框半径尺寸预设。 | [ { name, slug, size } ] |
color
与颜色相关的设置。
| Property | Description | Type | Default |
|---|---|---|---|
| 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 |
dimensions
与尺寸相关的设置。
| Property | Description | Type | Default |
|---|---|---|---|
| aspectRatio | 允许用户设置宽高比。 | boolean | false |
| defaultAspectRatios | 允许用户从默认宽高比集合中选择宽高比。 | boolean | true |
| aspectRatios | 允许用户为某些块定义宽高比。 | [ { name, slug, ratio } ] | |
| height | 允许用户设置自定义高度。 | boolean | false |
| minHeight | 允许用户设置自定义最小高度。 | boolean | false |
| minWidth | 允许用户设置自定义最小宽度。 | boolean | false |
| width | 允许用户设置自定义宽度。 | boolean | false |
| dimensionSizes | 维度块支持的尺寸尺寸预设。 | [ { name, slug, size } ] |
layout
与布局相关的设置。
| Property | Description | Type | Default |
|---|---|---|---|
| contentSize | 设置内容的最大宽度。 | string | |
| wideSize | 设置宽内容（.alignwide）的最大宽度。也用于计算流体字体大小时的最大视口。 | string | |
| allowEditing | 禁用布局 UI 控件。 | boolean | true |
| allowCustomContentAndWideSize | 启用或禁用自定义内容和宽尺寸控件。 | boolean | true |
lightbox
与灯箱相关的设置。
| Property | Description | Type | Default |
|---|---|---|---|
| enabled | 定义是否启用灯箱效果。 | boolean | |
| allowEditing | 定义是否在区块编辑器中显示灯箱用户界面。如果设置为 false，用户将无法在区块编辑器中更改灯箱设置。 | boolean |
position
与位置相关的设置。
| 属性 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| sticky | 允许用户设置粘性定位。 | boolean | false |
shadow
与阴影相关的设置。
| 属性 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| defaultPresets | 允许用户从默认的阴影预设中选择阴影。 | boolean | true |
| presets | 阴影选择器的阴影预设。 | [ { name, slug, shadow } ] |
spacing
与间距相关的设置。
| 属性 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| blockGap | 启用从 styles.spacing.blockGap 生成 --wp--style--block-gap。 | boolean, null | null |
| margin | 允许用户设置自定义边距。 | boolean | false |
| padding | 允许用户设置自定义内边距。 | boolean | false |
| units | 用户可用于间距值的单位列表。 | [ string ] | ["px","em","rem","vh","vw","%"] |
| customSpacingSize | 允许用户设置自定义间距大小。 | boolean | true |
| defaultSpacingSizes | 允许用户从默认的间距大小预设中选择间距大小。 | boolean | true |
| spacingSizes | 间距大小选择器的间距大小预设。 | [ { name, slug, size } ] | |
| spacingScale | 用于自动为间距大小选择器生成间距大小预设的设置。 | { operator, increment, steps, mediumStep, unit } |
typography
与排版相关的设置。
| 属性 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| defaultFontSizes | 允许用户从默认的字体大小预设中选择字体大小。 | boolean | true |
| customFontSize | 允许用户设置自定义字体大小。 | boolean | true |
| fontStyle | 允许用户设置自定义字体样式。 | boolean | true |
| fontWeight | 允许用户设置自定义字重。 | boolean | true |
| fluid | 启用流式排版，并允许用户设置全局流式排版参数。 | boolean, { minFontSize, maxViewportWidth, minViewportWidth } | false |
| letterSpacing | 允许用户设置自定义字母间距。 | boolean | true |
| lineHeight | 允许用户设置自定义行高。 | boolean | false |
| textIndent | 允许用户设置自定义首行缩进。 | boolean, string | "subsequent" |
| textAlign | 允许用户设置文本对齐方式。 | boolean | true |
| textColumns | 允许用户设置文本列数。 | boolean | false |
| textDecoration | 允许用户设置自定义文本装饰。 | boolean | true |
| textShadow | 允许用户设置自定义文本阴影。 | boolean | true |
| defaultTextShadowPresets | 允许用户从默认的文本阴影预设中选择文本阴影。 | boolean | true |
| textShadowPresets | 文本阴影选择器的文本阴影预设。 | [ { name, slug, textShadow } ] | |
| writingMode | 允许用户设置书写模式。 | boolean | false |
| textTransform | 允许用户设置自定义文本转换。 | boolean | true |
| dropCap | 启用首字下沉。 | boolean | true |
| fontSizes | 字体大小选择器的字体大小预设。 | [ { name, slug, size, fluid } ] | |
| fontFamilies | 字体族选择器的字体族预设。 | [ { name, slug, fontFamily, fontFace } ] |
viewport
用于响应式区块样式和区块可见性的视口断点设置。无效的断点值将被忽略。如果仅声明了一个有效的断点，它将按其配置的视口进行键控，并使用单个最大宽度查询。如果两个断点都无效，则使用默认断点。如果 mobile 大于或等于 tablet，则仅使用 mobile 断点。
| 属性 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| mobile | 移动样式的最大视口宽度。 | string | "480px" |
| tablet | 平板样式的最大视口宽度。当配置了两个断点时，平板样式适用于高于移动宽度且不超过此宽度的范围；或者当 tablet 是唯一的有效断点时，适用于不超过此宽度的范围。 | string | "782px" |
custom
生成形式为 --wp--custom--{key}--{nested-key}: {value}; 的自定义 CSS 自定义属性。camelCased（驼峰命名）的键将转换为 kebab-case（短横线命名），以遵循 CSS 属性命名规范。不同深度级别的键由 -- 分隔，因此键名中不应包含 --。
styles
设置 CSS 属性的结构化方式。顶层中的样式将添加到 body 选择器中。
在区块样式变体部分（带有 blockTypes 属性的 theme.json 文件）中，样式的作用域限定于列出的区块类型，并且在此级别也允许使用区块样式变体可用的响应式状态（@mobile、@tablet）和伪类选择器状态（:hover、:focus、:focus-visible、:active）。
background
背景样式。
| 属性 | 描述 | 类型 |
|---|---|---|
| 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 } |
| backgroundClip | 设置 background-clip CSS 属性。可选值为 border-box、padding-box、content-box 或 text。 | string, { ref } |
border
边框样式。
| 属性 | 描述 | 类型 |
|---|---|---|
| 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 } |
color
颜色样式。
| 属性 | 描述 | 类型 |
|---|---|---|
| background | 设置 background-color CSS 属性。 | string, { ref } |
| gradient | 设置 background CSS 属性。 | string, { ref } |
| text | 设置 color CSS 属性。 | string, { ref } |
css
设置自定义 CSS，以应用其他 theme.json 属性未涵盖的样式。
dimensions
尺寸样式。
| 属性 | 描述 | 类型 |
|---|---|---|
| aspectRatio | 设置 aspect-ratio CSS 属性。 | string, { ref } |
| height | 设置 height CSS 属性。 | string, { ref } |
| minHeight | 设置 min-height CSS 属性。 | string, { ref } |
| minWidth | 设置 min-width CSS 属性。 | string, { ref } |
| width | 设置 width CSS 属性。 | string, { ref } |
filter
CSS 和 SVG 滤镜样式。
| 属性 | 描述 | 类型 |
|---|---|---|
| duotone | 设置双色滤镜。 | string, { ref } |
outline
轮廓样式。
| 属性 | 描述 | 类型 |
|---|---|---|
| color | 设置 outline-color CSS 属性。 | string, { ref } |
| offset | 设置 outline-offset CSS 属性。 | string, { ref } |
| style | 设置 outline-style CSS 属性。 | string, { ref } |
| width | 设置 outline-width CSS 属性。 | string, { ref } |
shadow
盒阴影样式。
spacing
间距样式。
| 属性 | 描述 | 类型 |
|---|---|---|
| blockGap | 当 settings.spacing.blockGap 为 true 时，设置 --wp--style--block-gap CSS 自定义属性。 | string, { ref } |
| margin | 外边距样式。 | { top, right, bottom, left } |
| padding | 内边距样式。 | { top, right, bottom, left } |
typography
排版样式。
| 属性 | 描述 | 类型 |
|---|---|---|
| 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 } |
| textIndent | 设置 text-indent CSS 属性。 | string, { ref } |
| textAlign | 设置 text-align CSS 属性。 | string, { ref } |
| textColumns | 设置 column-count CSS 属性。 | string, { ref } |
| textDecoration | 设置 text-decoration CSS 属性。 | string, { ref } |
| textShadow | 设置 text-shadow CSS 属性。 | string, { ref } |
| writingMode | 设置 writing-mode CSS 属性。 | string, { ref } |
| textTransform | 设置 text-transform CSS 属性。 | string, { ref } |
customTemplates
在 templates 文件夹中定义的自定义模板的其他元数据。
| 属性 | 描述 | 类型 |
|---|---|---|
| name | templates 文件夹中模板的文件名（不含扩展名）。 | string |
| title | 模板标题，可翻译。 | string |
| postTypes | 可以使用此自定义模板的文章类型列表。 | [ string ] |
templateParts
在 parts 文件夹中定义的模板部件的其他元数据。
| 属性 | 描述 | 类型 |
|---|---|---|
| name | parts 文件夹中模板部件的文件名（不含扩展名）。 | string |
| title | 模板部件标题，可翻译。 | string |
| area | 该模板部件所使用的区域。存在用于 header 和 footer 值的区块变体，当 area 设置为其中之一时将使用这些变体。 | string |
patterns
要从 Pattern Directory 注册的图案 slug 数组。
类型：[ string ]。