Skip to main content

从 Ionic 7 更新到 8

¥Updating from Ionic 7 to 8

注意

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

¥This guide assumes that you have already updated your app to the latest version of Ionic 7. Make sure you have followed the Upgrading to Ionic 7 Guide before starting this guide.

重大变化

有关从 Ionic 7 到 Ionic 8 的重大更改的完整列表，请参阅 Ionic 框架存储库中的 重大变更文档。

¥For a complete list of breaking changes from Ionic 7 to Ionic 8, please refer to the breaking changes document in the Ionic Framework repository.

新手上路​

¥Getting Started

Angular​

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

    ¥Ionic 8 supports Angular 16+. Update to the latest version of Angular by following the Angular Update Guide.

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

    ¥Update to the latest version of 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。

¥Note: @ionic/angular-toolkit@11 requires a minimum of Angular 17. If you are still on Angular 16, then you may want to only update to to @ionic/angular-toolkit@10 instead.

  1. 更新从 @ionic/angular 的任何 IonBackButtonDelegate 导入以从 @ionic/angular 导入 IonBackButton。

    ¥Update any IonBackButtonDelegate imports from @ionic/angular to import IonBackButton from @ionic/angular instead.

React​

  1. Ionic 8 支持 React 17+。更新到最新版本的 React：

    ¥Ionic 8 supports React 17+. Update to the latest version of React:

npm install react@17 react-dom@17

  1. 更新到最新版本的 Ionic 8：

    ¥Update to the latest version of Ionic 8:

npm install @ionic/react@8 @ionic/react-router@8

Vue​

  1. Ionic 8 支持 Vue 3.0.6+。更新到最新版本的 Vue：

    ¥Ionic 8 supports Vue 3.0.6+. Update to the latest version of Vue:

npm install vue@^3.0.6 vue-router@^3.0.6

  1. 更新到最新版本的 Ionic 8：

    ¥Update to the latest version of Ionic 8:

npm install @ionic/vue@8 @ionic/vue-router@8

核心​

¥Core

  1. 更新到最新版本的 Ionic 8：

    ¥Update to the latest version of 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-background-color-step-[number] 来迁移背景颜色的 --ion-color-step-[number] 用法。

¥--ion-color-step-[number] usages for background color can be migrated by renaming the token to --ion-background-color-step-[number].

前：

¥Before:

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

后：

¥After:

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

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

¥--ion-color-step-[number] usages for text color can be migrated by renaming the token to --ion-text-color-step-[number] and subtracting the number from 1000.

前：

¥Before:

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

后：

¥After:

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/theme/variables.scss，然后再导入 src/global.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:

前：

¥Before:

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

后：

¥After:

  "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 属性的所有用法，因为旧的表单控制语法已被删除。

    ¥Migrate any remaining instances of Checkbox to use the modern form control syntax. Additionally, remove any usages of the legacy property as the legacy form control syntax has been removed.

输入​

¥Input

  1. 删除 size 属性的所有用法。应使用 CSS 来指定输入的可见宽度。

    ¥Remove any usages of the size property. CSS should be used to specify the visible width of the input instead.

  2. 删除 accept 属性的所有用法。

    ¥Remove any usages of the accept property.

  3. 迁移所有剩余的 Input 实例以使用 现代形式控制语法。此外，删除 legacy 属性的所有用法，因为旧的表单控制语法已被删除。

    ¥Migrate any remaining instances of Input to use the modern form control syntax. Additionally, remove any usages of the legacy property as the legacy form control syntax has been removed.

条目​

¥Item

  1. 删除 counter 或 counterFormatter 属性的任何用法。请改用 ion-input 和 ion-textarea 上的同名属性。

    ¥Remove any usages of the counter or counterFormatter properties. Use the properties of the same names on ion-input and ion-textarea instead.

  2. 删除 helper 或 error 插槽的所有使用。请改用 ion-input 和 ion-textarea 上的 helperText 和 errorText 属性。

    ¥Remove any usages of the helper or error slots. Use the helperText and errorText properties on ion-input and ion-textarea instead.

  3. 删除 fill 或 shape 属性的任何用法。请改用 ion-input、ion-textarea 和 ion-select 上的同名属性。

    ¥Remove any usages of the fill or shape properties. Use the properties of the same names on ion-input, ion-textarea, and ion-select instead.

¥Nav

  1. 在访问返回值之前将调用的 getLength 的任何用法更新为 await，因为此方法现在返回 Promise<number> 而不是 number。

    ¥Update any usages of getLength to await the call before accessing the returned value as this method now returns Promise<number> instead of number.

拾取器​

¥Picker

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

    ¥Ionic 8 now ships with an inline ion-picker component. Developers who wish to continue using the legacy picker should update any ion-picker usages to ion-picker-legacy. The pickerController import remains unchanged. Note that the ion-picker-legacy component will be removed in an upcoming major release of Ionic. Refer to the Picker documentation for usage information.

吐司​

¥Toast

  1. 从 ToastButton 中删除 cssClass 属性的所有用法。应改用 button CSS Shadow Part。

    ¥Remove any usages of the cssClass property from ToastButton. The button CSS Shadow Part should be used instead.

单选框​

¥Radio

  1. 迁移所有剩余的 Radio 实例以使用 现代形式控制语法。此外，删除 legacy 属性的所有用法，因为旧的表单控制语法已被删除。

    ¥Migrate any remaining instances of Radio to use the modern form control syntax. Additionally, remove any usages of the legacy property as the legacy form control syntax has been removed.

选择器​

¥Select

  1. 将 Select 的任何剩余实例迁移到使用 现代形式控制语法。此外，删除 legacy 属性的所有用法，因为旧的表单控制语法已被删除。

    ¥Migrate any remaining instances of Select to use the modern form control syntax. Additionally, remove any usages of the legacy property as the legacy form control syntax has been removed.

文本区​

¥Textarea

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

    ¥Migrate any remaining instances of Textarea to use the modern form control syntax. Additionally, remove any usages of the legacy property as the legacy form control syntax has been removed.

切换​

¥Toggle

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

    ¥Migrate any remaining instances of Toggle to use the modern form control syntax. Additionally, remove any usages of the legacy property as the legacy form control syntax has been removed.

需要升级帮助吗？​

¥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.

目录