# 迁移 Theme.json 至新版指南

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

## 从 v1 迁移至 v2

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

### 迁移步骤：

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

请参考[版本发布说明](https://make.wordpress.org/core/2022/01/08/updates-for-settings-styles-and-theme-json/)及[v1/v2版本参考文档](/docs/reference-guides/theme-json-reference/README.md)。

### 属性重命名对照表

| 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`