更新至 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. 将 `src/providers` 中的任何 Angular 服务复制到 `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 的styleUrls 选项，该选项属于 `@Component` 装饰器
   • 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 应用程序项目结构的示例。对于有 vanilla 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 替代方案。

有关更多详细信息，请查看路由器出口文档

覆盖层组件

在 Ionic 的早期版本中，覆盖层组件（如加载、吐司或警报）是同步创建的。在 Ionic v4 中，这些组件都是异步创建的。因此，API 现在是基于承诺的。

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

  alert.present();
}

在 v4 中，使用承诺

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

// Or using 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 团队在其文档网站上有一个很棒的指南，详细介绍了路由器。

为了提供用户习惯的平台特定动画，我们为 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 迁移到自定义元素，因此每个组件的标记都发生了重大变化。这些更改都已进行以遵循自定义元素规范，并在 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 培训、架构评审和迁移帮助。