从 Ionic 5 更新到 6

🌐 Updating from Ionic 5 to 6

note

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

重大变化

有关从 Ionic 5 到 Ionic 6 的所有重大更改列表，请参阅 Ionic 框架仓库中的重大更改文档。

新手上路

🌐 Getting Started

Angular

Ionic 6 支持 Angular 12 及更高版本。通过参考 Angular 更新指南更新到最新版本的 Angular。
更新到最新版本的 Ionic 6：

npm install @ionic/angular@6

如果你使用的是 Ionic Angular Server，请务必也进行更新：

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

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 而不是 setupIonicReact：

之前

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

...

setupConfig({
  mode: 'md'
});

之后

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

...

setupIonicReact({
  mode: 'md'
});

note

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

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

🌐 See the React Config Documentation for more examples.

将所有控制器的导入从 @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 插件：

🌐 Then, upgrade all Vue CLI plugins:

vue upgrade --next

更新到最新版本的 Ionic 6：

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

将以下 transformIgnorePatterns 添加到 package.json 中的 jest.config.js 或 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)"]
    }
  }

有关更多信息，请参见下面的测试部分。

🌐 See the Testing section below for more information.

移除之前从 @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>

note

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

将 ion-router-outlet 传入正在使用的任何 ion-tabs：

之前

<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

更新你的代码

🌐 Updating Your Code

日期时间

🌐 Datetime

移除对 placeholder、pickerOptions、pickerFormat、monthNames、monthShortNames、dayNames 和 dayShortNames 属性的任何使用。ion-datetime 现在会根据设备上设置的语言和地区自动格式化组件内显示的月份名称、星期名称和时间。有关更多信息，请参阅 ion-datetime 本地化文档。
删除对 text 和 placeholder CSS Shadow Parts 的任何使用。
移除任何 --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 解析日期文档。

note

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

图标

🌐 Icon

Ionic 6 现在随 Ionic 6 一起提供 Ionicons 6。请查看 Ionicons 6 重大更改指南并进行任何必要的更改。

🌐 Ionic 6 now ships with Ionicons 6. Review the Ionicons 6 Breaking Changes Guide and make any necessary changes.

输入

🌐 Input

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

🌐 Ensure null is not passed in as a value to the placeholder property. We recommend using undefined instead.

🌐 Modal

ion-modal 现在使用 Shadow DOM。更新任何针对 ion-modal 内部的样式，以使用 ion-modal CSS 变量或 ion-modal CSS Shadow 部分：

之前

ion-modal .modal-wrapper {
  /* Any custom styles here */
}

ion-modal ion-backdrop {
  /* Any custom styles here */
}

之后

ion-modal::part(content) {
  /* Any custom styles here */
}

ion-modal::part(backdrop) {
  /* Any custom styles here */
}

🌐 Popover

ion-popover 现在使用 Shadow DOM。更新所有针对 ion-popover 内部的样式，改为使用 ion-popover CSS 变量或 ion-popover CSS Shadow 部分：

之前

ion-popover .popover-arrow {
  /* Any custom styles here */
}

ion-popover ion-backdrop {
  /* Any custom styles here */
}

ion-popover .popover-content {
  /* Any custom styles here */
}

之后

ion-popover::part(arrow) {
  /* Any custom styles here */
}

ion-popover::part(backdrop) {
  /* Any custom styles here */
}

ion-popover::part(content) {
  /* Any custom styles here */
}

单选框

🌐 Radio

删除对 RadioChangeEventDetail 接口的任何使用。

🌐 Remove any usage of the RadioChangeEventDetail interface.

选择器

🌐 Select

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

🌐 Ensure null is not passed in as a value to the placeholder property. We recommend using undefined instead.

文本区

🌐 Textarea

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

🌐 Ensure null is not passed in as a value to the placeholder property. We recommend using undefined instead.

浏览器支持

🌐 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 >=60
Firefox >=63
Edge >=79
Safari >=13
iOS >=13

测试

🌐 Testing

Ionic 6 现在以 ES 模块的形式发布。ES 模块在所有主流浏览器中均受支持，并带来开发者体验和代码维护的改进。使用 Jest 进行测试的开发者需要更新他们的 Jest 配置，因为截至 Jest 27，Jest 并未完全支持 ES 模块。

🌐 Ionic 6 now ships as ES Modules. ES Modules are supported in all major browsers and bring developer experience and code maintenance improvements. Developers testing with Jest will need to update their Jest configuration as Jest does not have full support for ES Modules as of Jest 27.

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

🌐 This update involves using Babel to compile Ionic's ES Modules down to the CommonJS (CJS) format, a format that Jest can understand. Once Jest ships support for ES Modules, this change will no longer be necessary. See https://github.com/facebook/jest/issues/9430 for updates on ES Modules support in Jest.

如果你是从头开始创建一个新的 Ionic 应用，这个配置在我们的入门应用中已经为你完成。对于已有 Ionic 应用的用户，请按照以下步骤使 Jest 在 Ionic 6 上运行：

🌐 If you are starting fresh with a new Ionic app, this configuration is done for you in our starter applications. For those with existing Ionic apps, follow the steps below to get Jest working with Ionic 6:

在你的 Jest 配置中添加一个 transformIgnorePatterns 字段，其中包含相关的 Ionic 包。这通常可以在 package.json 的 jest.config.js 或 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)"]
    }
  }

note

如果你正在使用 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 命令：

🌐 For developers using Create React App (CRA), there is currently no way to update the transformIgnorePatterns in a Jest config file. This is a CRA restriction and not something Ionic has control over. We can, however, pass the transformIgnorePatterns directly into the react-scripts test command:

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

如果你仍然遇到问题，可以尝试以下几项操作：

🌐 If you are still running into issues, here are a couple things to try:

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

需要升级帮助吗？

🌐 Need Help Upgrading?

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

🌐 Be sure to look at the Ionic 6 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 required user action are listed on this page.

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

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

从 Ionic 5 更新到 6

新手上路

Angular

React

Vue

核心

更新你的代码

日期时间

图标

输入

弹出窗口

单选框

选择器

文本区

浏览器支持

测试

需要升级帮助吗？

目录

新手上路​

Angular​

React​

Vue​

核心​

更新你的代码​

日期时间​

图标​

输入​

模态​

弹出窗口​

单选框​

选择器​

文本区​

浏览器支持​

测试​

需要升级帮助吗？​

目录

新手上路

Angular

React

Vue

核心

更新你的代码

日期时间

图标

输入

模态

弹出窗口

单选框

选择器

文本区

浏览器支持

测试

需要升级帮助吗？