gutenbergdocs/docs/reference-guides/theme-json-reference/theme-json-migrations.md

迁移 Theme.json 至新版指南

本文档记录了不同版本 theme.json 之间的变更内容及升级方式。旧版本将持续获得支持，但建议升级至新版以获得持续的功能更新。

从 v1 迁移至 v2

升级至 v2 版本可启用新功能，并对旧功能命名进行统一优化。

迁移步骤：

1. 将 version 字段更新为 2
2. 检查并重命名已变更的属性（详见下表）

请参考版本发布说明及v1/v2版本参考文档。

属性重命名对照表

v1 版本	v2 版本
settings.border.customRadius	settings.border.radius
settings.spacing.customMargin	settings.spacing.margin
settings.spacing.customPadding	settings.spacing.padding
settings.typography.customLineHeight	settings.typography.lineHeight

新增属性

新增顶层属性：customTemplates、templateParts

配置项(sections)新增：

• settings.appearanceTools
• settings.border.color
• settings.border.style
• settings.border.width
• settings.color.background
• settings.color.defaultGradients
• settings.color.defaultPalette
• settings.color.text
• settings.spacing.blockGap
• settings.typography.fontFamilies
• settings.typography.fontStyle
• settings.typography.fontWeight
• settings.typography.letterSpacing
• settings.typography.textColumns
• settings.typography.textDecoration
• settings.typography.textTransform

样式项(styles)新增：

• styles.border.color
• styles.border.style
• styles.border.width
• styles.filter.duotone
• styles.spacing.blockGap
• styles.typography.fontFamily
• styles.typography.fontStyle
• styles.typography.fontWeight
• styles.typography.letterSpacing
• styles.typography.textColumns
• styles.typography.textDecoration
• styles.typography.textTransform

属性值变更

核心默认字体尺寸(settings.typography.fontSizes)已更新：移除了常规尺寸(Normal)与超大尺寸(Huge)（对应标识符为normal和huge），新增特大尺寸(Extra Large，标识符为x-large)。当界面控件显示核心默认值时，常规尺寸与超大尺寸将不再出现。但为确保现有内容正常显示，其CSS类及CSS自定义属性仍会保留。

从 v2 迁移至 v3

升级至 v3 版本将对预设默认值进行统一性优化。

迁移步骤：

1. 将 version 字段更新为 3
2. 根据下文说明配置变更的默认值

默认值变更

settings.typography.defaultFontSizes

在 theme.json v2 中，默认字体尺寸仅在主题未定义尺寸时显示。若主题提供的字体尺寸与默认标识符相同，则会始终覆盖默认值。

默认字体尺寸标识符包括：small、medium、large、x-large、xx-large

新增的 defaultFontSizes 选项可控制默认字体尺寸的显示与覆盖行为：

• 设为 true 时显示默认字体尺寸并禁止主题覆盖
• 设为 false 时隐藏默认字体尺寸并允许主题使用默认标识符

升级至 v3 后该值默认为 true，此举是为了与 settings.color.defaultPalette 等其他默认选项保持一致性，但与 v2 行为存在差异。

若需在 v3 中保持 v2 行为：

• 未定义任何 fontSizes 时，可保留 defaultFontSizes 或设为 true
• 已定义部分 fontSizes 时，需将 defaultFontSizes 设为 false

settings.spacing.defaultSpacingSizes

在 theme.json v2 中，存在两种设置主题级间距尺寸的方式：settings.spacing.spacingSizes 与 settings.spacing.spacingScale。若同时设置两者，仅会采用 spacingSizes 的数值。设置任一选项都会完全替换WordPress提供的默认间距尺寸。

WordPress提供的默认间距尺寸标识符包括：20、30、40、50、60、70、80

新增的 defaultSpacingSizes 选项可控制默认间距尺寸的显示与覆盖行为：

• 设为 true 时显示默认间距尺寸并禁止主题覆盖
• 设为 false 时隐藏默认间距尺寸并允许主题使用默认标识符

升级至 v3 后该值默认为 true，此举是为了与 settings.color.defaultPalette 等其他默认选项保持一致性，但与 v2 行为存在差异。

此外在 v3 中可同时设置 spacingSizes 与 spacingScale。当 spacingSizes 中定义的预设标识符与 spacingScale 生成的预设相同时，前者将覆盖后者。

若需在 v3 中保持 v2 行为：

• 未定义任何 spacingSizes 预设或 spacingScale 配置时，可保留 defaultSpacingSizes 或设为 true
• 若曾通过设置 spacingScale 为 { "steps": 0 } 禁用默认间距尺寸，需移除 spacingScale 配置并将 defaultSpacingSizes 设为 false
• 若仅通过 spacingScale 或 spacingSizes 之一定义预设，需将 defaultSpacingSizes 设为 false
• 若曾同时设置 spacingScale 与 spacingSizes，需移除 spacingSizes 配置并将 defaultSpacingSizes 设为 false