跳到主要内容
版本：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 {
    /* MD 全局应用变量 */
  }
}

在 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 来指定 input 的可见宽度。
  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 组件。希望继续使用旧版 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 论坛上发帖。

目录

编辑此页