title: "Theme.json 版本 3 参考（最新版）" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Theme Json Reference - Reference Guides - Repos

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 模式生成。

版本 3 的最新模式（包含 Gutenberg 插件的所有最新更改）可在 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 进行开发。

设置

区块编辑器及单个区块的设置项。这些设置包括： - 应向用户提供哪些自定义选项 - 用户可用的默认颜色、字体大小等配置 - 样式中使用的 CSS 自定义属性与类名 - 以及编辑器的默认布局（宽度与可用对齐方式）

useRootPaddingAwareAlignments

启用根内边距（来自 styles.spacing.padding 的值）应用于全宽块的内容，而非根块。

请注意，使用此设置时，styles.spacing.padding 应始终设置为一个对象，并分别声明 top、right、bottom、left 值。

注意： 仅顶级属性。在块中不可用。

appearanceTools

启用以下 UI 工具的设置：

背景：backgroundImage、backgroundSize
边框：color、radius、style、width
颜色：link、heading、button、caption
尺寸：aspectRatio、height、minHeight、width
定位：sticky
间距：blockGap、margin、padding
排版：lineHeight

背景

与背景相关的设置。

属性	描述	类型	默认值
backgroundImage	允许用户设置背景图片。	`boolean`	`false`
backgroundSize	允许用户设置与背景图片大小相关的值，包括尺寸、位置和重复控制。	`boolean`	`false`

边框

与边框相关的设置。

属性	描述	类型	默认值
color	允许用户设置自定义边框颜色。	`boolean`	`false`
radius	允许用户设置自定义边框圆角。	`boolean`	`false`
style	允许用户设置自定义边框样式。	`boolean`	`false`
width	允许用户设置自定义边框宽度。	`boolean`	`false`
radiusSizes	边框圆角选择器的预设圆角尺寸。	`[ { name, slug, size } ]`

color

Settings related to colors.

Property	Description	Type	Default
background	Allow users to set background colors.	`boolean`	`true`
custom	Allow users to select custom colors.	`boolean`	`true`
customDuotone	Allow users to create custom duotone filters.	`boolean`	`true`
customGradient	Allow users to create custom gradients.	`boolean`	`true`
defaultDuotone	Allow users to choose filters from the default duotone filter presets.	`boolean`	`true`
defaultGradients	Allow users to choose colors from the default gradients.	`boolean`	`true`
defaultPalette	Allow users to choose colors from the default palette.	`boolean`	`true`
duotone	Duotone presets for the duotone picker.	`[ { name, slug, colors } ]`
gradients	Gradient presets for the gradient picker.	`[ { name, slug, gradient } ]`
link	Allow users to set link colors in a block.	`boolean`	`false`
palette	Color palette presets for the color picker.	`[ { name, slug, color } ]`
text	Allow users to set text colors in a block.	`boolean`	`true`
heading	Allow users to set heading colors in a block.	`boolean`	`true`
button	Allow users to set button colors in a block.	`boolean`	`true`
caption	Allow users to set caption colors in a block.	`boolean`	`true`

dimensions

Settings related to dimensions.

Property	Description	Type	Default
aspectRatio	Allow users to set an aspect ratio.	`boolean`	`false`
defaultAspectRatios	Allow users to choose aspect ratios from the default set of aspect ratios.	`boolean`	`true`
aspectRatios	Allow users to define aspect ratios for some blocks.	`[ { name, slug, ratio } ]`
height	Allow users to set custom height.	`boolean`	`false`
minHeight	Allow users to set custom minimum height.	`boolean`	`false`
width	Allow users to set custom width.	`boolean`	`false`
dimensionSizes	Dimension size presets for dimension block supports.	`[ { name, slug, size } ]`

布局

与布局相关的设置。

属性	描述	类型	默认值
contentSize	设置内容的最大宽度。	`string`
wideSize	设置宽内容（`.alignwide`）的最大宽度。也用作计算流体字体大小时的最大视口。	`string`
allowEditing	禁用布局 UI 控件。	`boolean`	`true`
allowCustomContentAndWideSize	启用或禁用自定义内容和宽尺寸控件。	`boolean`	`true`

灯箱

与灯箱相关的设置。

属性	描述	类型	默认值
enabled	定义灯箱是否启用。	`boolean`
allowEditing	定义是否在区块编辑器中显示灯箱用户界面。如果设置为 `false`，用户将无法在区块编辑器中更改灯箱设置。	`boolean`

position

与位置相关的设置。

属性	描述	类型	默认值
sticky	允许用户设置粘性定位。	`boolean`	`false`

阴影

与阴影相关的设置。

属性	描述	类型	默认值
defaultPresets	允许用户从默认阴影预设中选择阴影。	`boolean`	`true`
presets	阴影选择器的阴影预设。	`[ { name, slug, shadow } ]`

spacing

Settings related to spacing.

Property	Description	Type	Default
blockGap	Enables `--wp--style--block-gap` to be generated from styles.spacing.blockGap.	`boolean`, `null`	`null`
margin	Allow users to set a custom margin.	`boolean`	`false`
padding	Allow users to set a custom padding.	`boolean`	`false`
units	List of units the user can use for spacing values.	`[ string ]`	`["px","em","rem","vh","vw","%"]`
customSpacingSize	Allow users to set custom space sizes.	`boolean`	`true`
defaultSpacingSizes	Allow users to choose space sizes from the default space size presets.	`boolean`	`true`
spacingSizes	Space size presets for the space size selector.	`[ { name, slug, size } ]`
spacingScale	Settings to auto-generate space size presets for the space size selector.	`{ operator, increment, steps, mediumStep, unit }`

typography

Settings related to typography.

Property	Description	Type	Default
defaultFontSizes	Allow users to choose font sizes from the default font size presets.	`boolean`	`true`
customFontSize	Allow users to set custom font sizes.	`boolean`	`true`
fontStyle	Allow users to set custom font styles.	`boolean`	`true`
fontWeight	Allow users to set custom font weights.	`boolean`	`true`
fluid	Enables fluid typography and allows users to set global fluid typography parameters.	`boolean`, `{ minFontSize, maxViewportWidth, minViewportWidth }`	`false`
letterSpacing	Allow users to set custom letter spacing.	`boolean`	`true`
lineHeight	Allow users to set custom line height.	`boolean`	`false`
textIndent	Allow users to set custom line indent.	`boolean`, `string`	`"subsequent"`
textAlign	Allow users to set the text align.	`boolean`	`true`
textColumns	Allow users to set the number of text columns.	`boolean`	`false`
textDecoration	Allow users to set custom text decorations.	`boolean`	`true`
writingMode	Allow users to set the writing mode.	`boolean`	`false`
textTransform	Allow users to set custom text transforms.	`boolean`	`true`
dropCap	Enable drop cap.	`boolean`	`true`
fontSizes	Font size presets for the font size selector.	`[ { name, slug, size, fluid } ]`
fontFamilies	Font family presets for the font family selector.	`[ { name, slug, fontFamily, fontFace } ]`

custom

生成形式为 --wp--custom--{key}--{nested-key}: {value}; 的自定义 CSS 自定义属性。camelCased 格式的键名会转换为 kebab-case 以遵循 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 }`

border

Border styles.

Property	Description	Type
color	Sets the `border-color` CSS property.	`string`, `{ ref }`
radius	Sets the `border-radius` CSS property.	`string`, `{ ref }`, `{ topLeft, topRight, bottomLeft, bottomRight }`
style	Sets the `border-style` CSS property.	`string`, `{ ref }`
width	Sets the `border-width` CSS property.	`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 属性未涵盖的样式。

dimensions

尺寸样式。

属性	描述	类型
aspectRatio	设置 `aspect-ratio` CSS 属性。	`string`, `{ ref }`
height	设置 `height` CSS 属性。	`string`, `{ ref }`
minHeight	设置 `min-height` 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

Typography styles.

Property	Description	Type
fontFamily	Sets the `font-family` CSS property.	`string`, `{ ref }`
fontSize	Sets the `font-size` CSS property.	`string`, `{ ref }`
fontStyle	Sets the `font-style` CSS property.	`string`, `{ ref }`
fontWeight	Sets the `font-weight` CSS property.	`string`, `{ ref }`
letterSpacing	Sets the `letter-spacing` CSS property.	`string`, `{ ref }`
lineHeight	Sets the `line-height` CSS property.	`string`, `{ ref }`
textIndent	Sets the `text-indent` CSS property.	`string`, `{ ref }`
textAlign	Sets the `text-align` CSS property.	`string`, `{ ref }`
textColumns	Sets the `column-count` CSS property.	`string`, `{ ref }`
textDecoration	Sets the `text-decoration` CSS property.	`string`, `{ ref }`
writingMode	Sets the `writing-mode` CSS property.	`string`, `{ ref }`
textTransform	Sets the `text-transform` CSS property.	`string`, `{ ref }`

customTemplates

Additional metadata for custom templates defined in the templates folder.

Property	Description	Type
name	Filename, without extension, of the template in the templates folder.	`string`
title	Title of the template, translatable.	`string`
postTypes	List of post types that can use this custom template.	`[ string ]`

templateParts

Additional metadata for template parts defined in the parts folder.

Property	Description	Type
name	Filename, without extension, of the template in the parts folder.	`string`
title	Title of the template, translatable.	`string`
area	The area the template part is used for. Block variations for `header` and `footer` values exist and will be used when the area is set to one of those.	`string`

patterns

一个从模式目录中注册的模式 slug 数组。

类型：[ string ]。