Skip to main content

从 Ionic 5 更新到 6

¥Updating from Ionic 5 to 6

注意

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

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

重大变化

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

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

新手上路​

¥Getting Started

Angular​

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

    ¥Ionic 6 supports Angular 12+. Update to the latest version of Angular by following the Angular Update Guide.

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

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

  1. 删除 Config.set() 的任何使用。相反，请在 IonicModule.forRoot() 中设置你的配置。有关更多示例，请参阅 角度配置文档。

    ¥Remove any usage of Config.set(). Instead, set your config in IonicModule.forRoot(). See the Angular Config Documentation for more examples.

  2. 删除先前从 @ionic/angular 导出的 setupConfig 函数的任何使用。请改为在 IonicModule.forRoot() 中设置你的配置。

    ¥Remove any usage of the setupConfig function previously exported from @ionic/angular. Set your config in IonicModule.forRoot() instead.

React​

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

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

npm install react@latest react-dom@latest

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

    ¥Update to the latest version of Ionic 6:

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

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

    ¥Update the test field in the scripts object of your package.json to include transformIgnorePatterns:

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

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

    ¥Import and call setupIonicReact in your App component file. If you are also using setupConfig, pass your config to setupIonicReact instead:

前

¥Before

App.tsx


import { setupConfig } from '@ionic/react';



...

setupConfig({
  mode: 'md'
});

后

¥After

App.tsx


import { setupIonicReact } from '@ionic/react';



...

setupIonicReact({
  mode: 'md'
});
注意

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

¥Developers must import and call setupIonicReact even if they are not setting custom config.

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

¥See the React Config Documentation for more examples.

  1. 将所有控制器导入从 @ionic/core 更新到 @ionic/core/components。作为示例，以下是 menuController 的迁移：

    ¥Update all controller imports from @ionic/core to @ionic/core/components. As an example, here is a migration for menuController:

前

¥Before



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


后

¥After



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


Vue​

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

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

npm install vue@3 vue-router@4

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

    ¥For apps that use the Vue CLI, install Vue CLI 5:

npm install -g @vue/cli@next

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

¥Then, upgrade all Vue CLI plugins:

vue upgrade --next

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

    ¥Update to the latest version of Ionic 6:

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

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

    ¥Add the following transformIgnorePatterns to either jest.config.js or the jest field in package.json:

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.

  1. 删除先前从 @ionic/vue 导出的 setupConfig 函数的任何使用。在安装 IonicVue 插件时设置你的配置。有关更多示例，请参阅 Vue 配置文档。

    ¥Remove any usage of the setupConfig function previously exported from @ionic/vue. Set your config when installing the IonicVue plugin instead. See the Vue Config Documentation for more examples.

  2. 将 useIonRouter 的 IonRouter 类型重命名为 UseIonRouterResult。

    ¥Rename the IonRouter type for useIonRouter to UseIonRouterResult.

  3. 将 useKeyboard 的 IonKeyboardRef 类型重命名为 UseKeyboardResult。

    ¥Rename the IonKeyboardRef type for useKeyboard to UseKeyboardResult.

  4. 重命名任何覆盖事件监听器以使用新格式：

    ¥Rename any overlay event listeners to use the new format:

前

¥Before

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

后

¥After

<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。

¥This applies to ion-action-sheet, ion-alert, ion-loading, ion-modal, ion-picker, ion-popover, and ion-toast.

  1. 将 ion-router-outlet 传递到正在使用的任何 ion-tabs 中：

    ¥Pass in an ion-router-outlet into any ion-tabs that are being used:

前

¥Before

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

<script>
  import { IonTabs, IonTabBar } from '@ionic/vue';
  import { defineComponent } from 'vue';

  export default defineComponent({
    components: { IonTabs, IonTabBar },
  });
</script>

后

¥After

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

<script>
  import { IonTabs, IonTabBar, IonRouterOutlet } from '@ionic/vue';
  import { defineComponent } from 'vue';

  export default defineComponent({
    components: { IonTabs, IonTabBar, IonRouterOutlet },
  });
</script>

  1. 选项卡内的其他路由应重写为同级路由而不是子路由：

    ¥Additional routes inside of tabs should be re-written as sibling routes instead of child routes:

前

¥Before

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')
      }
    ]
  }
]

后

¥After

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

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

    ¥Update to the latest version of Ionic 6:

npm install @ionic/core@6

更新你的代码​

¥Updating Your Code

日期时间​

¥Datetime

  1. 删除 placeholder、pickerOptions、pickerFormat、monthNames、monthShortNames、dayNames 和 dayShortNames 属性的任何用法。ion-datetime 现在根据设备上设置的语言和区域自动格式化组件内部显示的月份名称、日期名称和时间。请参阅 ion-datetime 本地化文档 了解更多信息。

    ¥Remove any usages of the placeholder, pickerOptions, pickerFormat, monthNames, monthShortNames, dayNames, and dayShortNames properties. ion-datetime now automatically formats the month names, day names, and time displayed inside of the component according to the language and region set on the device. See the ion-datetime Localization Documentation for more information.

  2. 删除 text 和 placeholder CSS 阴影部件的所有用法。

    ¥Remove any usages of the text and placeholder CSS Shadow Parts.

  3. 删除 --padding-bottom、--padding-end、--padding-start、--padding-top 和 --placeholder-color CSS 变量的任何用法。要自定义 ion-datetime 上的填充，你可以使用任何 padding CSS 属性。

    ¥Remove any usages of the --padding-bottom, --padding-end, --padding-start, --padding-top, and --placeholder-color CSS Variables. To customize the padding on ion-datetime, you can use any of the padding CSS properties.

  4. 删除 open 方法的任何使用。要在叠加层中显示日期时间，请将其放置在 ion-modal 或 ion-popover 组件内。请参阅 ion-datetime 用法示例 了解更多信息。

    ¥Remove any usage of the open method. To present the datetime in an overlay, place it inside of an ion-modal or an ion-popover component. See the ion-datetime Usage Examples for more information.

  5. 删除 displayFormat 或 displayTimezone 属性的任何使用。要解析 ionChange 事件负载中提供的 UTC 字符串，我们建议使用 date-fns。请参阅 ion-datetime 解析日期文档 的示例。

    ¥Remove any usage of the displayFormat or displayTimezone properties. To parse the UTC string provided in the payload of the ionChange event, we recommend using date-fns. See the ion-datetime Parsing Dates Documentation for examples.

注意

有关更多迁移示例，请参阅 日期时间迁移示例应用。

¥See the Datetime Migration Sample Application for more migration examples.

图标​

¥Icon

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 内部的样式以使用 Ionic 模态 CSS 变量 或 ion-modal CSS 阴影部分：

¥ion-modal now uses the Shadow DOM. Update any styles targeting the internals of ion-modal to use either the ion-modal CSS Variables or the ion-modal CSS Shadow Parts:

前

¥Before

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

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

后

¥After

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 阴影部分：

¥ion-popover now uses the Shadow DOM. Update any styles targeting the internals of ion-popover to use either ion-popover CSS Variables or the ion-popover CSS Shadow Parts:

前

¥Before

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

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

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

后

¥After

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:

  1. 将 transformIgnorePatterns 字段添加到你的 Jest 配置中，其中包含相关的 Ionic 包。这通常出现在 jest.config.js 或 package.json 的 jest 字段中：

    ¥Add a transformIgnorePatterns field to your Jest config that includes the relevant Ionic packages. This is typically found in jest.config.js or the jest field in package.json:

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。

¥If you are using Ionic React or Ionic Vue, be sure to add the appropriate packages to the transformIgnorePatterns array. For Ionic React this includes @ionic/react and @ionic/react-router. For Ionic Vue this includes @ionic/vue and @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:

  1. 验证 @babel/preset-env 是否包含在你的 项目范围的配置 中，而不是 文件相关配置 中。这通常意味着在 <project-root>/babel.config.json 中定义 Babel 配置。

    ¥Verify that @babel/preset-env is included in your project-wide configuration instead of your file-relative configuration. This typically means defining the Babel configuration in <project-root>/babel.config.json.

  2. 如果 package.json 文件中有 browserslist/test 字段，请确保将其设置为 current node。

    ¥If you have a browserslist/test field in package.json file, make sure it is set to 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.

目录