跳至主要内容
版本：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

核心​

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

以下更改并非更新至 Ionic 8 所必需，因为您的应用将继续正常运行。但是，我们建议您进行以下更改以确保您可以使用 Ionic 8 中的新功能。

亮色调色板​

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

/** Ionic CSS Variables **/
: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 {
    /* global app variables */
  }

  .ios body {
    /* global ios app variables */
  }

  .md body {
    /* global md app variables */
  }
}

在 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 相同，只是其特异性更高。

虽然迁移以包含新的暗色调色板文件不太可能导致重大更改，但如果在 body 元素上设置了自定义 CSS 变量，这些新的选择器可能会导致意外覆盖。我们建议更新将全局应用变量设置为目标 :root 选择器而不是 body 选择器的所有实例。

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

步骤颜色标记​

为了更好地支持 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 元素的字体大小，因为它可能会破坏动态字体缩放的正常运行。

想要禁用动态字体缩放的开发者可以在全局样式表中设置 --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

复选框​

  1. 迁移所有剩余的复选框实例以使用现代表单控件语法。此外，删除对 legacy 属性的所有使用，因为已删除了传统表单控件语法。

输入​

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

项目​

  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。

选择器​

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

提示​

  1. 移除ToastButton中的任何使用cssClass属性的地方。应改用button CSS 阴影部分。

单选按钮​

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

选择​

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

文本区域​

  1. 迁移任何剩余的文本区域实例以使用现代表单控件语法。此外，移除任何使用legacy属性的地方，因为已删除旧版表单控件语法。

切换​

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

需要升级帮助？​

请务必查看Ionic 8 更改记录指南。默认属性和 CSS 变量值有一些更改，开发人员可能需要了解。此页面上仅列出了需要用户操作的更改记录。

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

目录

编辑此页面