gutenbergdocs/reference-guides/theme-json-reference/theme-json-living.md

customTemplates（自定义模板）

用于存放模板文件夹中自定义模板的附加元数据。

属性	说明	类型
name	模板文件名称（不含扩展名），位于模板文件夹内。	字符串
title	模板标题（支持翻译）。	字符串
postTypes	可使用此自定义模板的文章类型列表。	[ 字符串 ]

templateParts（模板部件）

用于存放部件文件夹中模板部件的附加元数据。

属性	说明	类型
name	模板文件名称（不含扩展名），位于部件文件夹内。	字符串
title	模板标题（支持翻译）。	字符串
area	模板部件的适用区域。当设置为header或footer时，将使用对应的区块变体。	字符串

patterns（模式）

从模式目录注册的模式标识数组。

类型：[ 字符串 ]

Theme.json 第 3 版参考文档（最新版）

本文档是 theme.json 第 3 版的动态技术规范。该版本适用于 WordPress 6.6 及以上版本，以及最新的 Gutenberg 插件。

您可能对以下相关文档感兴趣：

• theme.json v1 技术规范
• theme.json v2 技术规范
• 从旧版 theme.json 迁移的参考指南

本参考指南列出了 theme.json 架构中定义的设置项和样式属性。关于如何在主题中使用 theme.json 文件的示例与指南，请参阅 theme.json 使用指南。

JSON 架构

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

包含 Gutenberg 插件所有最新更改的第 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

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

• 背景：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	字体家族选择器的字体家族预设。	[ { 名称, 别名, 字体家族, 字体文件 } ]

---