Ionic 3 升级 Ionic 4 迁移指南

Ionic 3 升级 Ionic 4 迁移指南

前言

Ionic 4 包含现代 Web API，如Custom Elements，CSS Variables和Shadow DOM。它彻底与开发框架无关，做为 Web 开发人员的UI库，不管他们决定使用什么前端工具或代码框架。

在Vue，React或根本没有框架中使用Ionic也是如此。 就像Ionic Angular同样，咱们的目标是使用传统标准在最流行的框架中轻松采用Ionic。使用Vue开发Ionic应用参考这里

Ionic Framework 4使用标准 Web API 从头开始重建，每一个组件都打包为符合标准的 Web 组件。 经过单独依赖浏览器 API 支持并保持每一个组件的公共 API 稳定，这使框架的核心保持友好。

与此相反，依赖于特定框架的客户端运行时和组件模型，这些模型可能会随着时间的推移而发生变化（须要进行代价高昂的重写和API更改）。 Ionic 4的目的是为了不可怕的“框架流失”，所以咱们能够花更多的时间专一于咱们最擅长的事情：为Web开发人员建立出色的UI组件。 简而言之，咱们永远不想再次重写Ionic的组件。

v4中最大的变化之一是Ionic为每一个组件使用Web组件。咱们甚至构建了一个名为Stencil的工具来帮助咱们更轻松地完成这项工做并开源！

除了避免框架流失外，Web Components还将更多工做推向浏览器并须要更少的代码，从而为负载和启动时间带来关键性能改进，这对于构建高性能Progressive Web Apps相当重要，这是项目向前发展的重点。

对于那些刚接触Web Components的人来讲，该术语指的是一系列Web API，它们在现代移动和桌面浏览器上获得普遍支持，例如Custom Elements和Shadow DOM。虽然Web Components已经被炒做了几年，但咱们认为浏览器和开发人员的支持终于达到了临界质量，使它们为黄金时段作好了准备。但咱们并非惟一的 - 许多传统框架和UI库也开始采用它们（例如：Angular Elements）。

因为您可能已经对浏览器支持感到疑惑：Ionic无缝地填充了极少数自己不支持Web组件的浏览器。相当重要的是，polyfill只会根据功能检测下载到须要它们的客户端，所以绝大多数用户甚至不须要请求其中任何一个。使人惊讶的是，移动设备对Web组件API提供了更普遍的支持，使得polyfill更加没必要要。

当Ionic 2发布时，Angular CLI，构建工具和 Router 出现了大量的流失性和不肯定性。所以，Ionic必须构建本身的许多工具版本。快进到今天，Angular经过一些出色的工具填补了这些空白，如今是Ionic利用它，并遵循Angular社区中设定的标准的时候了。

从Ionic 4开始，咱们很高兴彻底接受Angular CLI和 Router ！这些更新容许咱们用官方的，维护良好的Angular工具替换ionic-app-scripts和Ionic的 Router 。

这意味着Angular开发人员如今能够直接将Angular CLI用于Ionic应用程序，并随时了解Angular继续取得的使人敬畏的进展。咱们还想确保Ionic Angular为Framework使用了defacto标准 Router ，所以Angular开发人员能够再次使用他们熟悉的API。咱们将可以更深刻地了解咱们的文档和即将发布的博客文章。

虽然这对现有的Ionic Angular开发人员来讲是一个改变，可是对于该项目来讲这是一个长期的胜利，由于Ionic能够更多地关注组件，而不是更多的没必要要的复杂工具，以及Ionic Angular开发人员的胜利，如今可使用一流的Angular工具和惯例。

概述

将现有应用程序从 Ionic 3 迁移到 4 时，建议参照如下过程：

1. 使用 blank 启动器生成一个新项目(参考 建立应用)。

2. 从 src/providers 复制全部 Angular services到 src/app/services。

   • Services 应该包括 @Injectable() 装饰器中的 { providedIn: 'root' } 。更多详情, 请参考 Angular provider docs.
3. 复制应用程序的其余根级别项目 (例如, pipes, components 等) 并保持目录结构从 src/components 变动为 src/app/components.
4. 从 src/app/app.scss 复制全局 Sass 样式到 src/global.scss

5. 复制应用程序的其他部分, page 到 page 或者 feature 到 feature, 注意如下几点:

   • 默认状况下，Emulated Shadow DOM处 于启用状态
   • Page/component 的 Sass 不该再包含在 page/component 标记中，而应使用 Angular @Component 装饰器 的 styleUrls 选项
   • RxJS 已从 v5 更新为 v6 (参考 RxJS变动)
   • 某些生命周期 hooks 应该被 Angular 的 hooks 取代 (参考 生命周期事件)
   • 可能须要更改某些标记 (有迁移工具可用, 参考 标记变动)

在许多状况下，使用 Ionic CLI 生成新对象而后复制代码也能够很好地工做。 例如：ionic g service weather 将建立一个 Weather 服务和测试 shell。 而后能够根据须要对旧代码中的代码进行微小修改。 这有助于确保遵循正确的结构。 这也会为单元测试生成 shell。

项目结构

Ionic 3 应用程序和 Ionic 4 应用程序之间的主要变化之一是项目总体的布局和结构。 在第3版中，Ionic 应用程序有一个自定义约定，用于如何设置应用程序以及该文件夹结构应该是什么样子。 在 v4 中，已更改成遵循每一个受支持框架的建议的设置。

例如，若是某个应用程序正在使用 Angular，那么该项目结构将与 Angular CLI 应用程序彻底相同。 这种变化虽然须要一点适应过程，但有助于保持常见模式和文档的一致性。

上面的比较是 v4 应用程序项目结构的一个示例。 对于有 Angular 项目经验的开发人员来讲，这应该让人感到很是熟悉。

有一个 src/ 目录做为应用程序的主页。 这包括 index.html，全部资产，环境变量和任何特定于应用程序的配置文件。

在迁移应用程序以利用此新布局时，建议使用 CLI 建立新 "base" 项目。 而后，使用新项目布局，逐个迁移应用程序的功能。Pages/components/等，应该移到 src/app/ 文件夹中。

包名变动

V4 版本的另外一个变化是 Ionic 的实际包名。 对于 v4，包名称现为 @ionic/angular。 迁移应用程序时，将 imports 从 ionic-angular 更新为 @ionic/angular。

RxJS变动

因为从 RxJS v5 更改成 v6，所以须要进行一些次要的 RxJS 更改。 有关详细信息，请参阅 RxJS 迁移指南。

生命周期事件

一些 Ionic 生命周期事件等同于 Angular 生命周期 hooks。 例如，ionViewDidLoad() 扮演与 Angular OnInit 生命周期 hook（ngOnInit()）相同的角色。 在这种状况下，请使用 Angular 生命周期 hooks。

叠加组件

在 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();
}

In v4, promises are used:

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 中，对导航和路由进行了重大更改。 NavController 和 ion-nav 现已弃用。 虽然他们仍然可使用，但仅当用于应用程序没有使用延迟加载时。

代替 ion-nav 和 NavController，Ionic 建议使用官方 Angular Router 进行路由。 Angular 团队在其文档网站上有一个 优秀指南，详细介绍了 Router。

一个关键的区别是，Ionic 应用程序不使用 router-outlet 组件，而是使用 ion-router-outlet。 该组件具备与标准 Angular router-outlet 相同的功能，可是包含 transitions。

延迟加载

另外一个变化是在 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 已移至 Custom Elements，所以每一个组件的标记都发生了重大变化。 这些更改都是按照 Custom Elements 规范进行的，并已记录在 Github 上专门的文件中。

为帮助完成这些标记更改，咱们发布了基于 TSLint 的迁移工具 ，它能够检测问题，甚至能够自动修复其中的一些问题。