版本：v8

从 Ionic 5 升级到 6

备注

本指南假设您已将应用升级到 Ionic 5 的最新版本。在开始本指南之前，请确保您已按照升级到 Ionic 5 指南进行操作。

破坏性变更

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

开始之前

Angular

Ionic 6 支持 Angular 12+。请按照 Angular 更新指南更新到最新版本的 Angular。
更新到 Ionic 6 的最新版本：

npm install @ionic/angular@6

如果您使用 Ionic Angular Server，请确保也更新它：

npm install @ionic/angular@6 @ionic/angular-server@6

移除所有 Config.set() 的使用。改为在 IonicModule.forRoot() 中设置配置。更多示例请参阅 Angular 配置文档。
移除所有之前从 @ionic/angular 导出的 setupConfig 函数的使用。改为在 IonicModule.forRoot() 中设置配置。

React

Ionic 6 支持 React 17+。更新到最新版本的 React：

npm install react@latest react-dom@latest

更新到 Ionic 6 的最新版本：

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

更新 package.json 中 scripts 对象里的 test 字段，包含 transformIgnorePatterns：

"scripts": {
  "test": "react-scripts test --transformIgnorePatterns 'node_modules/(?!(@ionic/react|@ionic/react-router|@ionic/core|@stencil/core|ionicons)/)'",
  ...
}

在您的 App 组件文件中导入并调用 setupIonicReact。如果您也使用了 setupConfig，请将您的配置传递给 setupIonicReact：

之前

App.tsx
import { setupConfig } from '@ionic/react';

...

setupConfig({
  mode: 'md'
});

之后

App.tsx
import { setupIonicReact } from '@ionic/react';

...

setupIonicReact({
  mode: 'md'
});

备注

即使不设置自定义配置，开发者也必须导入并调用 setupIonicReact。

更多示例请参阅 React 配置文档。

将所有控制器导入从 @ionic/core 更新为 @ionic/core/components。以下以 menuController 为例进行迁移：

之前

import { menuController } from '@ionic/core';

之后

import { menuController } from '@ionic/core/components';

Vue

Ionic 6 支持 Vue 3.0.6+。更新到最新版本的 Vue：

npm install vue@3 vue-router@4

对于使用 Vue CLI 的应用，安装 Vue CLI 5：

npm install -g @vue/cli@next

然后，升级所有 Vue CLI 插件：

vue upgrade --next

更新到 Ionic 6 的最新版本：

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

将以下 transformIgnorePatterns 添加到 jest.config.js 或 package.json 的 jest 字段中：

jest.config.js
module.exports = {
  ...
  transformIgnorePatterns: ['/node_modules/(?!@ionic/vue|@ionic/vue-router|@ionic/core|@stencil/core|ionicons)']
}

package.json
  {
    ...
    "jest": {
      "transformIgnorePatterns": ["/node_modules/(?!@ionic/vue|@ionic/vue-router|@ionic/core|@stencil/core|ionicons)"]
    }
  }

更多信息请参阅下面的测试部分。

移除所有之前从 @ionic/vue 导出的 setupConfig 函数的使用。改为在安装 IonicVue 插件时设置配置。更多示例请参阅 Vue 配置文档。
将 useIonRouter 的 IonRouter 类型重命名为 UseIonRouterResult。
将 useKeyboard 的 IonKeyboardRef 类型重命名为 UseKeyboardResult。
重命名所有覆盖层事件监听器以使用新格式：

之前

<ion-modal
  :is-open="modalOpenRef"
  @onWillPresent="onModalWillPresentHandler"
  @onDidPresent="onModalDidPresentHandler"
  @onWillDismiss="onModalWillDismissHandler"
  @onDidDismiss="onModalDidDismissHandler"
>
  ...
</ion-modal>

之后

<ion-modal
  :is-open="modalOpenRef"
  @willPresent="onModalWillPresentHandler"
  @didPresent="onModalDidPresentHandler"
  @willDismiss="onModalWillDismissHandler"
  @didDismiss="onModalDidDismissHandler"
>
  ...
</ion-modal>

备注

这适用于 ion-action-sheet、ion-alert、ion-loading、ion-modal、ion-picker、ion-popover 和 ion-toast。

在所有使用的 ion-tabs 中传入一个 ion-router-outlet：

之前

<ion-tabs>
  <ion-tab-bar slot="bottom"> ... </ion-tab-bar>
</ion-tabs>

<script setup lang="ts">
  import { IonTabs, IonTabBar } from '@ionic/vue';
</script>

之后

<ion-tabs>
  <ion-router-outlet></ion-router-outlet>
  <ion-tab-bar slot="bottom"> ... </ion-tab-bar>
</ion-tabs>

<script setup lang="ts">
  import { IonTabs, IonTabBar, IonRouterOutlet } from '@ionic/vue';
</script>

标签页内的额外路由应重写为同级路由，而不是子路由：

之前

const routes: Array<RouteRecordRaw> = [
  {
    path: '/',
    redirect: '/tabs/tab1'
  },
  {
    path: '/tabs/',
    component: Tabs,
    children: [
      {
        path: '',
        redirect: 'tab1'
      },
      {
        path: 'tab1',
        component: () => import('@/views/Tab1.vue'),
        children: {
          {
            path: 'view',
            component: () => import('@/views/Tab1View.vue')
          }
        }
      },
      {
        path: 'tab2',
        component: () => import('@/views/Tab2.vue')
      },
      {
        path: 'tab3',
        component: () => import('@/views/Tab3.vue')
      }
    ]
  }
]

之后

const routes: Array<RouteRecordRaw> = [
  {
    path: '/',
    redirect: '/tabs/tab1',
  },
  {
    path: '/tabs/',
    component: Tabs,
    children: [
      {
        path: '',
        redirect: 'tab1',
      },
      {
        path: 'tab1',
        component: () => import('@/views/Tab1.vue'),
      },
      {
        path: 'tab1/view',
        component: () => import('@/views/Tab1View.vue'),
      },
      {
        path: 'tab2',
        component: () => import('@/views/Tab2.vue'),
      },
      {
        path: 'tab3',
        component: () => import('@/views/Tab3.vue'),
      },
    ],
  },
];

Core

更新到 Ionic 6 的最新版本：

npm install @ionic/core@6

更新您的代码

Datetime（日期时间）

移除所有 placeholder、pickerOptions、pickerFormat、monthNames、monthShortNames、dayNames 和 dayShortNames 属性的使用。ion-datetime 现在会根据设备设置的语言和地区自动格式化组件内部显示的月份名称、日期名称和时间。更多信息请参阅 ion-datetime 本地化文档。
移除所有 text 和 placeholder CSS Shadow Parts（CSS 影子部件）的使用。
移除所有 --padding-bottom、--padding-end、--padding-start、--padding-top 和 --placeholder-color CSS 变量的使用。要自定义 ion-datetime 的内边距，您可以使用任何 padding CSS 属性。
移除所有 open 方法的使用。要在覆盖层中显示日期时间，请将其放在 ion-modal 或 ion-popover 组件内。更多信息请参阅 ion-datetime 使用示例。
移除所有 displayFormat 或 displayTimezone 属性的使用。要解析 ionChange 事件负载中提供的 UTC 字符串，我们推荐使用 date-fns。示例请参阅 ion-datetime 解析日期文档。

备注

更多迁移示例请参阅 Datetime 迁移示例应用。

Icon（图标）

Ionic 6 现在附带 Ionicons 6。请查看 Ionicons 6 破坏性变更指南并进行必要的更改。

Input（输入框）

确保不要将 null 作为值传递给 placeholder 属性。我们建议改用 undefined。

Modal（模态框）

ion-modal 现在使用 Shadow DOM（影子 DOM）。更新所有针对 ion-modal 内部结构的样式，使用 ion-modal CSS 变量或 ion-modal CSS 影子部件：

之前

ion-modal .modal-wrapper {
  /* 任何自定义样式 */
}

ion-modal ion-backdrop {
  /* 任何自定义样式 */
}

之后

ion-modal::part(content) {
  /* 任何自定义样式 */
}

ion-modal::part(backdrop) {
  /* 任何自定义样式 */
}

Popover（弹出框）

ion-popover 现在使用 Shadow DOM（影子 DOM）。更新所有针对 ion-popover 内部结构的样式，使用 ion-popover CSS 变量或 ion-popover CSS 影子部件：

之前

ion-popover .popover-arrow {
  /* 任何自定义样式 */
}

ion-popover ion-backdrop {
  /* 任何自定义样式 */
}

ion-popover .popover-content {
  /* 任何自定义样式 */
}

之后

ion-popover::part(arrow) {
  /* 任何自定义样式 */
}

ion-popover::part(backdrop) {
  /* 任何自定义样式 */
}

ion-popover::part(content) {
  /* 任何自定义样式 */
}

Radio（单选框）

移除所有 RadioChangeEventDetail 接口的使用。

Select（选择框）

确保不要将 null 作为值传递给 placeholder 属性。我们建议改用 undefined。

Textarea（文本域）

确保不要将 null 作为值传递给 placeholder 属性。我们建议改用 undefined。

浏览器支持

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

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

Chrome >=60
Firefox >=63
Edge >=79
Safari >=13
iOS >=13

测试

Ionic 6 现在以 ES 模块形式发布。ES 模块在所有主流浏览器中都受支持，并带来了开发体验和代码维护方面的改进。使用 Jest 进行测试的开发人员需要更新其 Jest 配置，因为截至 Jest 27，Jest 对 ES 模块的完全支持尚不完善。

此更新涉及使用 Babel 将 Ionic 的 ES 模块编译为 CommonJS (CJS) 格式，这是 Jest 能够理解的格式。一旦 Jest 支持 ES 模块，此更改将不再必要。有关 Jest 中 ES 模块支持的更新，请参阅 https://github.com/facebook/jest/issues/9430。

如果您是从头开始一个新的 Ionic 应用，此配置已在我们的入门应用中为您完成。对于现有的 Ionic 应用，请按照以下步骤使 Jest 与 Ionic 6 配合工作：

在 Jest 配置中添加一个 transformIgnorePatterns 字段，其中包含相关的 Ionic 包。这通常位于 jest.config.js 或 package.json 的 jest 字段中：

jest.config.js
module.exports = {
  ...
  transformIgnorePatterns: ['/node_modules/(?!@ionic/core|@stencil/core|ionicons)']
}

package.json
  {
    ...
    "jest": {
      "transformIgnorePatterns": ["/node_modules/(?!@ionic/core|@stencil/core|ionicons)"]
    }
  }

备注

如果您使用 Ionic React 或 Ionic Vue，请确保将相应的包添加到 transformIgnorePatterns 数组中。对于 Ionic React，这包括 @ionic/react 和 @ionic/react-router。对于 Ionic Vue，这包括 @ionic/vue 和 @ionic/vue-router。

对于使用 Create React App (CRA) 的开发者，目前无法在 Jest 配置文件中更新 transformIgnorePatterns。这是 CRA 的限制，Ionic 无法控制。但是，我们可以直接将 transformIgnorePatterns 传递给 react-scripts test 命令：

package.json
"scripts": {
  "test": "react-scripts test --transformIgnorePatterns 'node_modules/(?!(@ionic/react|@ionic/react-router|@ionic/core|@stencil/core|ionicons)/)'",
  ...
}

如果您仍然遇到问题，可以尝试以下方法：

确保 @babel/preset-env 包含在您的项目范围配置中，而不是文件相对配置中。这通常意味着在 <project-root>/babel.config.json 中定义 Babel 配置。
如果您的 package.json 文件中有 browserslist/test 字段，请确保其设置为 current node。

需要升级帮助？

请务必查看 Ionic 6 破坏性变更指南。其中包含许多默认属性和 CSS 变量值的变更，开发者可能需要了解。本页仅列出了需要用户操作的破坏性变更。

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

开始之前​

Angular​

React​

Vue​

Core​

更新您的代码​

Datetime（日期时间）​

Icon（图标）​

Input（输入框）​

Modal（模态框）​

Popover（弹出框）​

Radio（单选框）​

Select（选择框）​

Textarea（文本域）​

浏览器支持​

测试​

需要升级帮助？​

Contents

开始之前

Angular

React

Vue

Core

更新您的代码

Datetime（日期时间）

Icon（图标）

Input（输入框）

Modal（模态框）

Popover（弹出框）

Radio（单选框）

Select（选择框）

Textarea（文本域）

浏览器支持

测试

需要升级帮助？