迁移 Theme.json 至新版本

本指南记录了不同 theme.json 版本间的变更及升级方法。旧版本将继续获得支持，但建议进行升级，因为新功能开发将集中于新版本。

从 v1 迁移到 v2

升级到 v2 版本可启用一些新功能，并调整部分旧功能的命名，使其更加统一。

如何从 v1 迁移到 v2：

1. 将 version 更新为 2。
2. 如果你正在使用已更新的属性，请重命名它们（见下文）。

请参考版本发布的开发说明以及 v1 和 v2 版本各自的参考文档。

Renamed properties

新增属性

新增顶级属性：customTemplates、templateParts。

设置部分新增：

• 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.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 标识）已从列表中移除，并添加了特大尺寸（对应 x-large 标识）。当 UI 控件显示核心提供的默认值时，将不再包含常规和超大尺寸。不过，它们的 CSS 类和 CSS 自定义属性仍会入队，以确保使用它们的现有内容仍能正常工作。

从 v2 迁移到 v3

升级到 v3 版本调整了预设默认值，使其彼此之间更加一致。

如何从 v2 迁移到 v3：

1. 将 version 更新为 3。
2. 配置已更改的默认值（见下文）。

默认设置变更

settings.typography.defaultFontSizes

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

默认的 fontSizes 标识符包括：small、medium、large、x-large 和 xx-large。

新的 defaultFontSizes 选项可控制是否显示默认字体大小，并防止这些默认值被覆盖。

• 设置为 true 时，将显示默认字体大小并防止其被主题覆盖。
• 设置为 false 时，将隐藏默认字体大小并允许主题使用默认标识符。

切换到 v3 时，此选项默认值为 true。这是为了与其他 default* 选项（如 settings.color.defaultPalette）保持一致，但与 v2 的行为不同。

要在 v3 的 theme.json 中保持类似 v2 的行为：

• 若未定义任何 fontSizes，可省略 defaultFontSizes 或将其设为 true。
• 若已定义部分 fontSizes，请将 defaultFontSizes 设为 false。

settings.spacing.defaultSpacingSizes

在 theme.json v2 中，有两个设置可用于定义主题级别的间距尺寸：settings.spacing.spacingSizes 和 settings.spacing.spacingScale。同时设置 spacingSizes 和 spacingScale 将仅使用 spacingSizes 中的值。设置其中任何一个都将始终替换 WordPress 提供的整套默认间距尺寸。

WordPress 提供的默认 spacingSizes 标识符为：20、30、40、50、60、70 和 80。

新的 defaultSpacingSizes 选项提供了控制是否显示默认间距尺寸以及防止这些默认值被覆盖的能力。

• 设置为 true 时，将显示默认间距尺寸并防止它们被主题覆盖。
• 设置为 false 时，将隐藏默认间距尺寸并允许主题使用默认标识符。

切换到 v3 时，defaultSpacingSizes 默认为 true。这是为了与其他 default* 选项（如 settings.color.defaultPalette）的工作方式保持一致，但与 v2 中的行为不同。

此外，在 v3 中，可以同时设置 spacingSizes 和 spacingScale。在 spacingSizes 中定义的、标识符与 spacingSizes 生成的预设匹配的预设将覆盖生成的预设。

要在 v3 的 theme.json 中保持与 v2 类似的行为：

• 如果您没有定义任何 spacingSizes 预设或 spacingScale 配置，可以省略 defaultSpacingSizes 或将其设置为 true。
• 如果您曾通过将 spacingScale 设置为 { "steps": 0 } 来禁用默认间距尺寸，请移除 spacingScale 配置并将 defaultSpacingSizes 设置为 false。
• 如果您仅为预设定义了 spacingScale 或 spacingSizes 中的一个，请将 defaultSpacingSizes 设置为 false。
• 如果您同时定义了 spacingScale 和 spacingSizes，请移除 spacingSizes 配置 并 将 defaultSpacingSizes 设置为 false。