110 lines
5.2 KiB
Markdown
110 lines
5.2 KiB
Markdown
# 迁移 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` |