跳到主要内容
版本：v8

从 Ionic 7 更新至 8

备注

本指南假设您已将应用更新至 Ionic 7 的最新版本。请确保在开始本指南前已遵循 升级至 Ionic 7 指南。

破坏性变更

有关从 Ionic 7 到 Ionic 8 的完整破坏性变更列表，请参考 Ionic Framework 仓库中的 破坏性变更文档。

开始之前​

Angular​

  1. Ionic 8 支持 Angular 16+。请按照 Angular 更新指南 更新至最新版本的 Angular。

  2. 更新至 Ionic 8 的最新版本：

npm install @ionic/angular@latest

如果您使用了 Ionic Angular Server 和 Ionic Angular Toolkit，请务必同时更新它们：

npm install @ionic/angular@latest @ionic/angular-server@latest @ionic/angular-toolkit@11

注意：@ionic/angular-toolkit@11 要求最低 Angular 17。如果您仍在使用 Angular 16，则建议仅更新至 @ionic/angular-toolkit@10。

  1. 将任何从 @ionic/angular 导入的 IonBackButtonDelegate 改为从 @ionic/angular 导入 IonBackButton。

React​

  1. Ionic 8 支持 React 17+。更新至最新版本的 React：
npm install react@17 react-dom@17
  1. 更新至 Ionic 8 的最新版本：
npm install @ionic/react@8 @ionic/react-router@8

Vue​

  1. Ionic 8 支持 Vue 3.0.6+。更新至最新版本的 Vue：
npm install vue@^3.0.6 vue-router@^3.0.6
  1. 更新至 Ionic 8 的最新版本：
npm install @ionic/vue@8 @ionic/vue-router@8

Core​

  1. 更新至 Ionic 8 的最新版本：
npm install @ionic/core@8

建议的更改​

以下更改并非更新至 Ionic 8 的必需步骤，您的应用将继续正常运行。然而，我们建议进行以下更改，以确保您能够使用 Ionic 8 中的新功能。

浅色调色板​

之前的版本在 theme/variables.scss 中为浅色调色板定义了一组默认颜色变量：

/** Ionic CSS 变量 **/
:root {
  /** primary **/
  --ion-color-primary: #3880ff;
  --ion-color-primary-rgb: 56, 128, 255;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  /* ... */
}

在 Ionic Framework 版本 8 中，只要导入了 core.css，就会包含这些颜色变量。应删除 theme/variables.scss 中定义的颜色变量，以避免覆盖导入的默认变量，并确保应用始终使用最新的调色板。

自定义此颜色调色板的开发者可以继续保留自定义变量值，但任何使用默认值的变量都应删除。

您可以在 Ionic v8 公告 中了解更多关于新调色板的信息。

深色调色板​

在之前的版本中，建议按以下方式定义深色调色板：

@media (prefers-color-scheme: dark) {
  body {
    /* 全局应用变量 */
  }

  .ios body {
    /* 全局 iOS 应用变量 */
  }

  .md body {
    /* 全局 Material Design 应用变量 */
  }
}

在 Ionic Framework 版本 8 中，深色调色板通过可导入的 CSS 文件分发。以下是在 Angular 中导入深色调色板文件的示例：

/* @import '@ionic/angular/css/palettes/dark.always.css'; */
/* @import "@ionic/angular/css/palettes/dark.class.css"; */
@import '@ionic/angular/css/palettes/dark.system.css';

深色调色板现在应用于 :root 选择器，而不是 body 选择器。:root 选择器代表 <html> 元素，与 html 选择器相同，但具有更高的优先级。

迁移以包含新的深色调色板文件不太可能导致破坏性变更，但如果自定义 CSS 变量在 body 元素上设置，这些新的选择器可能导致意外的覆盖。我们建议更新任何设置全局应用变量的实例，改为针对 :root 选择器。

有关新的深色调色板文件的更多信息，请参阅 深色模式文档。

阶梯颜色标记​

为了更好地支持 Ionic 8 中的高对比度调色板，引入了独立的文本和背景颜色阶梯标记。之前文本和背景颜色都由单一的 --ion-color-step-[number] 标记控制。

使用上述新导入的深色调色板也将导入这些新的阶梯颜色标记。然而，开发者需要更新应用中手动定义的任何阶梯颜色标记。

用于背景颜色的 --ion-color-step-[number] 用法可以通过将标记重命名为 --ion-background-color-step-[number] 来迁移。

之前：

button { background: var(--ion-color-step-400); }

之后：

button { background: var(--ion-background-color-step-400); }

用于文本颜色的 --ion-color-step-[number] 用法可以通过将标记重命名为 --ion-text-color-step-[number] 并从 1000 中减去数字来迁移。

之前：

button { color: var(--ion-color-step-400); }

之后：

button { color: var(--ion-text-color-step-600); /* 1000 - 400 = 600 */ }

阶梯颜色生成器 已更新，可生成文本和背景颜色的阶梯变量。

动态字体​

core.css 文件已更新，默认启用动态字体缩放。

--ion-default-dynamic-font 变量已被移除，并替换为 --ion-dynamic-font。

之前通过在全局样式表中激活动态字体缩放而选择使用它的开发者，可以通过移除其自定义 CSS 恢复默认设置。这样做后，他们的应用将无缝地继续使用动态字体缩放，与之前一样。需要注意的是，应避免更改 html 元素的 font-size，因为它可能破坏动态字体缩放的正常功能。

希望禁用动态字体缩放的开发者可以在其全局样式表中设置 --ion-dynamic-font: initial;。但是，这不推荐，因为它可能给依赖放大字体大小的用户带来可访问性挑战。

有关动态字体的更多信息，请参阅 动态字体缩放文档。

（仅限 Angular）angular.json CSS 导入顺序​

angular.json 文件当前在导入 src/global.scss 之前导入 src/theme/variables.scss。这可能导致在自定义新的 深色调色板 更改时应用错误的样式。

我们建议先导入 src/global.scss 文件：

之前：

  "styles": ["src/theme/variables.scss", "src/global.scss"],

之后：

  "styles": ["src/global.scss", "src/theme/variables.scss"],

必需的更改​

浏览器支持​

Ionic 支持的浏览器列表已更改。请查看 浏览器支持指南，确保您将应用部署到支持的浏览器。

如果您有 browserslist 或 .browserslistrc 文件，请使用以下内容更新：

Chrome >=89
ChromeAndroid >=89
Firefox >=75
Edge >=89
Safari >=15
iOS >=15

Checkbox​

  1. 迁移 Checkbox 的任何剩余实例以使用 现代表单控件语法。此外，移除任何 legacy 属性的使用，因为旧版表单控件语法已被移除。

Input​

  1. 移除 size 属性的任何使用。应使用 CSS 来指定输入框的可见宽度。
  2. 移除 accept 属性的任何使用。
  3. 迁移 Input 的任何剩余实例以使用 现代表单控件语法。此外，移除任何 legacy 属性的使用，因为旧版表单控件语法已被移除。

Item​

  1. 移除 counter 或 counterFormatter 属性的任何使用。改为使用 ion-input 和 ion-textarea 上的同名属性。
  2. 移除 helper 或 error 插槽的任何使用。改为使用 ion-input 和 ion-textarea 上的 helperText 和 errorText 属性。
  3. 移除 fill 或 shape 属性的任何使用。改为使用 ion-input、ion-textarea 和 ion-select 上的同名属性。
  1. 更新任何 getLength 的使用，在访问返回值之前 await 调用，因为此方法现在返回 Promise<number> 而不是 number。

Picker​

  1. Ionic 8 现在附带一个内联的 ion-picker 组件。希望继续使用旧版选择器的开发者应将任何 ion-picker 使用更新为 ion-picker-legacy。pickerController 导入保持不变。请注意，ion-picker-legacy 组件将在 Ionic 的下一主要版本中移除。有关使用信息，请参阅 Picker 文档。

Toast​

  1. 移除 ToastButton 中 cssClass 属性的任何使用。应改用 button CSS Shadow Part。

Radio​

  1. 迁移 Radio 的任何剩余实例以使用 现代表单控件语法。此外，移除任何 legacy 属性的使用，因为旧版表单控件语法已被移除。

Select​

  1. 迁移 Select 的任何剩余实例以使用 现代表单控件语法。此外，移除任何 legacy 属性的使用，因为旧版表单控件语法已被移除。

Textarea​

  1. 迁移 Textarea 的任何剩余实例以使用 现代表单控件语法。此外，移除任何 legacy 属性的使用，因为旧版表单控件语法已被移除。

Toggle​

  1. 迁移 Toggle 的任何剩余实例以使用 现代表单控件语法。此外，移除任何 legacy 属性的使用，因为旧版表单控件语法已被移除。

需要升级帮助？​

请务必查看 Ionic 8 破坏性变更指南。默认属性和 CSS 变量值有几处更改，开发者可能需要了解。本页仅列出了需要用户操作的破坏性变更。

如果您需要升级帮助，请在 Ionic 论坛 上发帖。

Contents

编辑此页