版本：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 提供者文档。
复制应用的其他根级别项目（管道、组件等），注意目录结构从 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，但提供了基于堆栈的导航（标签页）和动画。

有关 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 路由器的 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 迁移的部分可能会成为有用的参考资料。使用空白初始模板生成一个新的 Ionic 4 项目（参见开始开发应用）。花时间熟悉 Ionic 4 组件。祝您构建愉快！

需要帮助？

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

从 Ionic 3 升级到 4​

包名变更​

项目结构​

RxJS 变更​

生命周期事件​

叠加层组件​

导航​

懒加载​

标记语言变更​

从 Ionic 1 升级到 4​

从 Ionic 1 到 Ionic 4：涉及哪些工作？​

建议策略​

从 AngularJS 迁移到 Angular​

Ionic 变更​

需要帮助？​

Contents