升级到 Ionic 4

从 Ionic 3 升级到 4

备注

本指南假设您已将应用升级到 Ionic 3 的最新版本。如果您仍在使用 Ionic 1 或 2，请务必遵循 从 Ionic 1 升级到 4 指南。

重大变更

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

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

1. 使用 blank 起始模板生成一个新项目（参见 开始创建应用）
2. 将 Angular 服务从 src/providers 复制到 src/app/services
   • 服务应在 @Injectable() 装饰器中包含 { providedIn: 'root' }。详情请参阅 Angular 服务提供者文档。
3. 复制应用的其他根级别项目（管道、组件等），注意目录结构从 src/components 更改为 src/app/components 等。
4. 将全局 Sass 样式从 src/app/app.scss 复制到 src/global.scss
5. 逐页或逐功能地复制应用的其余部分，同时注意以下事项：
   • 模拟 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

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

Ionic 3

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 培训、架构审查和迁移协助。