版本：v7

更新到 Ionic 4

从 Ionic 3 更新到 4

备注

本指南假设您已将应用更新到 Ionic 3 的最新版本。如果您使用 Ionic 1 或 2，请确保遵循从 Ionic 1 更新到 4 的指南。

重大变更

有关从 Ionic 3 到 Ionic 4 的完整重大变更列表，请参阅 Ionic Framework 仓库中的重大变更文档。

我们建议在将现有应用从 Ionic 3 迁移到 4 时采用以下通用流程：

使用 blank 启动模板生成一个新项目（参见启动应用）
将任何 Angular 服务从 src/providers 复制到 src/app/services
- 服务应在 @Injectable() 装饰器中包含 { providedIn: 'root' }。详情请参阅 Angular provider 文档。
复制应用的其他根级项（管道、组件等），注意目录结构从 src/components 变为 src/app/components 等。
将全局 Sass 样式从 src/app/app.scss 复制到 src/global.scss
逐页或逐功能复制应用的其余部分，注意以下事项：
- 模拟 Shadow DOM 默认开启
- 页面/组件 Sass 不应再包装在页面/组件标签中，应使用 Angular 的 @Component 装饰器的 styleUrls 选项
- RxJS 已从 v5 更新到 v6（参见 RxJS 变更）
- 某些生命周期钩子应替换为 Angular 的钩子（参见生命周期事件）
- 可能需要进行标记更改（有迁移工具可用，参见标记更改）

在许多情况下，使用 Ionic CLI 生成新对象然后复制代码也效果很好。例如：ionic g service weather 将创建一个 Weather 服务外壳和测试。然后可以根据需要稍作修改，从旧项目中复制代码。这有助于确保遵循正确的结构。这也会生成单元测试的外壳。

包名称变更

在 Ionic 4 中，包名称为 @ionic/angular。卸载 Ionic 3 并使用新包名称安装 Ionic 4：

$ npm uninstall ionic-angular
$ npm install @ionic/angular@v4-lts

在迁移应用时，将导入从 ionic-angular 更新为 @ionic/angular。

项目结构

Ionic 3 应用和 Ionic 4 应用之间的主要变化之一是整体项目布局和结构。在 v3 中，Ionic 应用对于如何设置应用以及文件夹结构的外观有自定义约定。在 v4 中，这已更改为遵循每个受支持框架的推荐设置。

例如，如果应用使用 Angular，其项目结构将与 Angular CLI 应用完全一致。这一变化虽然不太难以适应，但有助于保持通用模式和文档的一致性。

Ionic 4
Ionic 3

src/
├── app/
│   ├── about/
│   ├── home/
│   ├── app-routing.module.ts
│   ├── app.component.html
│   ├── app.component.spec.ts
│   ├── app.component.ts
│   └── app.module.ts
├── assets/
├── environments/
├── theme/
├── global.scss
├── index.html
├── karma.conf.js
├── main.ts
├── polyfills.ts
├── test.ts
├── tsconfig.app.json
└── tsconfig.spec.json
.gitignore
angular.json
ionic.config.json
package.json
tsconfig.json
tslint.json

src/
├── app/
│   ├── app.component.html
│   ├── app.html
│   ├── app.module.ts
│   ├── app.scss
│   └── main.ts
├── assets/
├── pages/
│   ├── about/
│   ├── home/
├── theme/
├── index.html
├── manifest.json
└── service-worker.js
.gitignore
ionic.config.json
package.json
tsconfig.json
tslint.json

上述对比是 v4 应用项目结构的示例。对于有纯 Angular 项目经验的开发者来说，这应该感觉很熟悉。

有一个 src/ 目录作为应用的主目录。其中包含 index.html、任何静态资源、环境配置以及任何应用特定的配置文件。

在迁移应用以利用这种新布局时，建议使用 CLI 创建一个新的项目"基础"。然后，使用新的项目布局，逐个功能地迁移应用的各个部分。页面/组件等应移至 src/app/ 文件夹。

确保您的 Ionic 配置文件具有适当的 type。v3 的项目类型是 ionic-angular。v4 的项目类型是 angular。如果此值不正确，CLI 可能会调用错误的构建脚本。

请参阅以下 ionic.config.json 示例：

{
  "name": "my-app",
  "type": "angular"
}

RxJS 变更

在 V3 和 V4 之间，RxJS 更新到了版本 6。这改变了许多运算符和 RxJS 核心函数的导入路径。详情请参阅 RxJS 迁移指南。

生命周期事件

使用 V4，我们现在能够利用 Angular 提供的典型事件。但在某些情况下，您可能希望在组件路由更改期间动画完成时访问触发的事件。在这种情况下，ionViewWillEnter、ionViewDidEnter、ionViewWillLeave 和 ionViewDidLeave 已从 V3 移植过来。使用这些事件来协调与 Ionic 自身动画系统的操作。

旧的事件如 ionViewDidLoad、ionViewCanLeave 和 ionViewCanEnter 已被移除，应使用适当的 Angular 替代方案。

有关更多详细信息，请查看 router-outlet 文档

覆盖层组件

在先前版本的 Ionic 中，覆盖层组件（如 Loading、Toast 或 Alert）是同步创建的。在 Ionic v4 中，这些组件都是异步创建的。因此，API 现在基于 Promise。

// v3
showAlert() {
  const alert = this.alertCtrl.create({
    message: "Hello There",
    subHeader: "I'm a subheader"
  });

  alert.present();
}

在 v4 中，使用 Promise：

showAlert() {
  this.alertCtrl.create({
    message: "Hello There",
    subHeader: "I'm a subheader"
  }).then(alert => alert.present());
}

// 或使用 async/await

async showAlert() {
  const alert = await this.alertCtrl.create({
    message: "Hello There",
    subHeader: "I'm a subheader"
  });

  await alert.present();
}

在 V4 中，导航发生了最大的变化。现在，不再使用 Ionic 自己的 NavController，而是与官方的 Angular Router 集成。这不仅在应用中提供了一致的路由体验，而且更加可靠。Angular 团队在其文档网站上有一个优秀的指南，详细介绍了 Router。

为了提供用户习惯的平台特定动画，我们为 Angular 应用创建了 ion-router-outlet。其行为类似于 Angular 的 router-outlet，但提供了基于堆栈的导航（tabs）和动画。

有关 V4 项目中导航工作的详细说明，请查看 Angular 导航指南。

懒加载

由于导航已更改，V4 中的懒加载机制也已更改。

在 v3 中，典型的懒加载设置如下：

// home.page.ts
@IonicPage({
  segment: 'home'
})
@Component({ ... })
export class HomePage {}

// home.module.ts
@NgModule({
  declarations: [HomePage],
  imports: [IonicPageModule.forChild(HomePage)]
})
export class HomePageModule {}

然而，在 v4 中，懒加载是通过 Angular router 的 loadChildren 方法完成的：

// home.module.ts
@NgModule({
  imports: [IonicModule, RouterModule.forChild([{ path: '', component: HomePage }])],
  declarations: [HomePage],
})
export class HomePageModule {}

// app.module.ts
@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    IonicModule.forRoot(),
    RouterModule.forRoot([
      { path: 'home', loadChildren: './pages/home/home.module#HomePageModule' },
      { path: '', redirectTo: 'home', pathMatch: 'full' },
    ]),
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

有关 V4 项目中懒加载的详细说明，请查看 Angular 导航指南。

标记更改

由于 v4 迁移到了 Custom Elements，每个组件的标记都有显著变化。所有这些更改都是为了遵循 Custom Elements 规范，并已记录在 GitHub 上的专用文件中。

为帮助处理这些标记更改，我们发布了基于 TSLint 的迁移工具，它可以检测问题，甚至可以自动修复其中一些问题。

从 Ionic 1 更新到 4

Ionic 1 到 Ionic 4：涉及哪些内容？

从 Ionic 1 迁移到 Ionic 4 涉及从 AngularJS（即 Angular 1）迁移到 Angular 7+。这些版本之间存在许多架构差异，因此部分应用代码必须重写。工作量取决于应用的复杂性和大小。

一个好消息是，您熟悉和喜爱的 V1 中的 Ionic UI 组件大多没有太大变化。

在开始升级之前，请考虑以下几点：

应用复杂性：自然，应用越大越复杂，迁移所需时间就越长。
框架支持：2019 年，Ionic 将发布对 React 的全面支持。您也可以无需框架使用 Ionic Framework 组件。由于这些还未达到生产就绪状态，我们建议坚持使用 Angular 或等待其他框架支持可用。
预算和团队组成：迁移项目的时长将根据团队规模、应用复杂性和分配给过渡的时间而有所不同。

建议策略

一旦您的开发团队确定了开始迁移的良好时间框架，Ionic 建议冻结 Ionic 1 应用的功能并整理代码：修复任何主要错误，消除技术债务，并根据需要进行重组。然后，确定哪些功能需要迁移，哪些要放弃。

一旦 Ionic 1 应用稳定，创建一个新的 Ionic 4 项目。开发团队的大部分注意力应放在新项目上；只有在 Ionic 1 应用中修复错误，以确保过渡尽可能快速顺利地进行。

一旦团队确信 Ionic 4 应用已稳定并实现了核心功能集，就可以关闭 Ionic 1 应用。

从 AngularJS 迁移到 Angular

请参考官方的 Angular 升级指南信息。

Ionic 变更

我们上面的 Ionic 3 到 Ionic 4 迁移部分可能是有用的参考。使用 blank 启动模板生成一个新的 Ionic 4 项目（参见启动应用）。花些时间熟悉 Ionic 4 组件。祝构建愉快！

需要帮助？

如果您的团队需要迁移协助，请联系我们！Ionic 提供咨询服务，包括 Ionic 4 培训、架构审查和迁移协助。

从 Ionic 3 更新到 4​

包名称变更​

项目结构​

RxJS 变更​

生命周期事件​

覆盖层组件​

导航​

懒加载​

标记更改​

从 Ionic 1 更新到 4​

Ionic 1 到 Ionic 4：涉及哪些内容？​

建议策略​

从 AngularJS 迁移到 Angular​

Ionic 变更​

需要帮助？​

目录