Skip to main content

从 Ionic 7 更新到 8

🌐 Updating from Ionic 7 to 8

note

本指南假设你已经将应用更新到最新版本的 Ionic 7。请确保在开始本指南之前，你已经遵循了 升级到 Ionic 7 指南 的步骤。

重大变化

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

新手上路​

🌐 Getting Started

Angular​

  1. Ionic 8 支持 Angular 16 及更高版本。通过参考 Angular 更新指南 更新到最新版本的 Angular。
  2. 更新到最新版本的 Ionic 8：
npm install @ionic/angular@latest

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

🌐 If you are using Ionic Angular Server and Ionic Angular Toolkit, be sure to update those as well:

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

🌐 Recommended Changes

以下更改不是升级到 Ionic 8 所必需的，因为你的应用将继续工作。然而，我们建议进行以下更改，以确保你能够使用 Ionic 8 中的新功能。

🌐 The following changes are not required to update to Ionic 8 as your application will continue to work. However, we recommend making the following changes to ensure you can use the new features in Ionic 8.

浅色调色板​

🌐 Light Palette

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

🌐 Previous versions defined a set of default color variables for the light palette in 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 中定义的颜色变量，以避免覆盖导入的默认变量，并确保应用始终使用最新的调色板。

🌐 In Ionic Framework version 8, these color variables are included as long as core.css is imported. The color variables defined in theme/variables.scss should be removed to avoid overriding the imported default variables and ensure the app is always using the latest palette.

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

🌐 Developers who are customizing this color palette can continue to keep the custom variables values, but any of the variables that use the default values should be removed.

你可以在Ionic v8 公告中阅读有关新配色方案的更多信息。

🌐 You can read more about the new color palette in the Ionic v8 announcement.

深色调色板​

🌐 Dark Palette

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

🌐 In previous versions, it was recommended to define the dark palette in the following way:

@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 中导入深色调色板文件的示例：

🌐 In Ionic Framework version 8, the dark palette is being distributed via css files that can be imported. Below is an example of importing a dark palette file in 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 相同，只是其特异性更高。

🌐 The dark palette is now applied to the :root selector instead of the body selector. The :root selector represents the <html> element and is identical to the selector html, except that its specificity is higher.

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

🌐 While migrating to include the new dark palette files is unlikely to cause breaking changes, these new selectors can lead to unexpected overrides if custom CSS variables are being set on the body element. We recommend updating any instances where global application variables are set to target the :root selector instead.

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

🌐 For more information on the new dark palette files, refer to the Dark Mode documentation.

步骤颜色标记​

🌐 Step Color Tokens

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

🌐 To better support the high contrast palette in Ionic 8, separate step colors tokens have been introduced for text and background color. Previously both text and background color were controlled by a single set of --ion-color-step-[number] tokens.

使用上面提到的新导入的暗色调调色板也将导入这些新的步骤颜色令牌。然而，开发者需要更新在应用中手动定义的任何步骤颜色令牌。

🌐 Using the newly imported dark palette mentioned above will also import these new step color tokens. However, developers will need to update any step color tokens that were manually defined in an application.

用于 背景颜色 的 --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 */ }

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

🌐 The stepped color generator has been updated to generate text and background color stepped variables.

动态字体​

🌐 Dynamic Font

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

🌐 The core.css file has been updated to enable dynamic font scaling by default.

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

🌐 The --ion-default-dynamic-font variable has been removed and replaced with --ion-dynamic-font.

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

🌐 Developers who had previously chosen dynamic font scaling by activating it in their global stylesheets can revert to the default setting by removing their custom CSS. In doing so, their application will seamlessly continue utilizing dynamic font scaling as it did before. It's essential to note that altering the font-size of the html element should be avoided, as it may disrupt the proper functioning of dynamic font scaling.

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

🌐 Developers who want to disable dynamic font scaling can set --ion-dynamic-font: initial; in their global stylesheets. However, this is not recommended because it may introduce accessibility challenges for users who depend on enlarged font sizes.

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

🌐 For more information on the dynamic font, refer to the Dynamic Font Scaling documentation.

(仅限 Angular) angular.json CSS 导入顺序​

🌐 (Angular Only) angular.json CSS import order

angular.json 文件目前在导入 src/global.scss 之前导入了 src/theme/variables.scss。这可能会在自定义新的 暗色调色板 更改时导致应用不正确的样式。

🌐 The angular.json file currently imports src/theme/variables.scss before importing src/global.scss. This may cause the incorrect styles to be applied when customizing the new Dark Palette changes.

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

🌐 We recommend importing the src/global.scss file first instead:

之前:

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

之后:

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

所需的更改​

🌐 Required Changes

浏览器支持​

🌐 Browser Support

Ionic 支持的浏览器列表已发生变化。请查看 浏览器支持指南，以确保你将应用部署到受支持的浏览器上。

🌐 The list of browsers that Ionic supports has changed. Review the Browser Support Guide to ensure you are deploying apps to supported browsers.

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

🌐 If you have a browserslist or .browserslistrc file, update it with the following content:

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 上的同名属性。

🌐 Nav

  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 属性的使用，因为旧版表单控件语法已被移除。

需要升级帮助吗？​

🌐 Need Help Upgrading?

请务必查看 Ionic 8 重大更改指南。默认属性和 CSS 变量值有若干更改，开发者可能需要注意。本页面仅列出了需要用户操作的重大更改。

🌐 Be sure to look at the Ionic 8 Breaking Changes Guide. There were several changes to default property and CSS Variable values that developers may need to be aware of. Only the breaking changes that require user action are listed on this page.

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

🌐 If you need help upgrading, please post a thread on the Ionic Forum.

目录