将 Theme.json 迁移到较新版本

本文档记录了不同 theme.json 版本之间的变更以及升级方法。继续使用旧版本仍将受到支持。建议进行升级，因为新的开发工作将在较新版本中持续进行。

从 v1 迁移到 v2

升级到 v2 启用了一些新功能，并调整了一些旧功能的命名，使其彼此更加一致。

如何从 v1 迁移到 v2：

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

请参阅发布说明 dev note for the release 以及 v1 和 v2 版本各自的 reference documents。

重命名的属性

新增的属性

新增顶级属性：customTemplates、templateParts。

对 settings 的添加项：

• 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 slugs），并添加了 Extra Large（带有 x-large slug）。当 UI 控件显示核心提供的默认值时，Normal 和 Huge 将不再出现。但是，它们的 CSS 类和 CSS Custom Properties 仍会被入队，以确保使用它们的内容仍能按预期工作。

从 v2 迁移到 v3

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

如何从 v2 迁移到 v3：

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

更改的默认值

settings.typography.defaultFontSizes

在 theme.json v2 中，仅当未定义主题大小时才会显示默认字体大小。如果主题提供了与默认值具有相同 slugs 的字体大小，则会始终覆盖这些默认值。

默认的 fontSizes slugs 为：small、medium、large、x-large 和 xx-large。

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

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

切换到 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 slugs 为：20、30、40、50、60、70 和 80。

新的 defaultSpacingSizes 选项允许控制是否显示默认间距大小并防止这些默认值被覆盖。

• 设置为 true 时，它将显示默认间距大小并防止其被主题覆盖。
• 设置为 false 时，它将隐藏默认间距大小并允许主题使用默认 slugs。

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

此外，在 v3 中，可以同时设置 spacingSizes 和 spacingScale。在 spacingSizes 中定义的预设，如果其 slugs 与从 spacingSizes 生成的预设匹配，则将会覆盖生成的预设。

要在 v3 theme.json 中保持与 v2 类似的行为：
* 如果您没有定义任何 spacingSizes 预设或 spacingScale 配置，可以省略 defaultSpacingSizes 或将其设置为 true。
* 如果您通过设置 spacingScale 为 { "steps": 0 } 禁用了默认间距大小，请移除 spacingScale 配置并将 defaultSpacingSizes 设置为 false。
* 如果您仅为预设定义了 spacingScale 或 spacingSizes 中的一个，请将 defaultSpacingSizes 设置为 false。
* 如果您同时定义了 spacingScale 和 spacingSizes，请移除 spacingSizes 配置 和 将 defaultSpacingSizes 设置为 false。