更新到 Ionic 4

🌐 Updating to Ionic 4

从 Ionic 3 更新到 4

🌐 Updating from Ionic 3 to 4

note

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

重大变化

有关从 Ionic 3 到 Ionic 4 的所有重大更改列表，请参阅 Ionic 框架仓库中的重大更改文档。

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

🌐 We suggest the following general process when migrating an existing application from Ionic 3 to 4:

使用 blank 启动器生成一个新项目（参见启动应用）
将任何 Angular 服务从 src/providers 复制到 src/app/services
- 服务应包括 { providedIn: 'root' } 在 @Injectable() 装饰器中。有关详细信息，请参见 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 的钩子替换（参见生命周期事件）
- 可能需要修改标记（有迁移工具可用，请参见 Markup Changes）

在许多情况下，使用 Ionic CLI 生成一个新对象然后复制代码也非常有效。例如：ionic g service weather 将创建一个 Weather 服务及其测试的框架。然后可以从旧项目中复制代码，并根据需要进行少量修改。这有助于确保遵循正确的结构。这也会为单元测试生成框架。

🌐 In many cases, using the Ionic CLI to generate a new object and then copying the code also works very well. For example: ionic g service weather will create a shell Weather service and test. The code can then be copied from the older project with minor modifications as needed. This helps to ensure the proper structure is followed. This also generates shells for unit tests.

包名称的变化

🌐 Changes in Package Name

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

🌐 In Ionic 4, the package name is @ionic/angular. Uninstall Ionic 3 and install Ionic 4 using the new package name:

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

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

🌐 While migrating an app, update the imports from ionic-angular to @ionic/angular.

项目结构

🌐 Project structure

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

🌐 One of the major changes between an Ionic 3 app and an Ionic 4 app is the overall project layout and structure. In v3, Ionic apps had a custom convention for how an app should be set up and what that folder structure should look like. In v4, this has been changed to follow the recommended setup of each supported framework.

例如，如果一个应用使用 Angular，那么该项目结构将完全与 Angular CLI 应用的结构相同。这个变化虽然不太难适应，但有助于保持常见模式和文档的一致性。

🌐 For example, if an app is using Angular, that project structure will be exactly what an Angular CLI app would be. This change, while not too difficult to accommodate, helps to keep common patterns and documentation consistent.

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 项目经验的开发者来说，这应该会非常熟悉。

🌐 The above comparison is an example of a v4 app's project structure. For developers with experience in a vanilla Angular project, this should feel really familiar.

有一个 src/ 目录，它作为应用的主目录。这包括 index.html、任何资源、环境配置以及任何特定于应用的配置文件。

🌐 There is a src/ directory that acts as the home for the app. This includes the index.html, any assets, environment configuration, and any app-specific config files.

在迁移应用以利用这个新的布局时，建议使用 CLI 创建一个新的项目“基础”。然后，使用新的项目布局，逐步迁移应用的各个功能。页面/组件等应移动到 src/app/ 文件夹中。

🌐 While migrating an app to take advantage of this new layout, it is suggested that a new project "base" is made with the CLI. Then, with the new project layout, migrate the features of the app piece by piece. Pages/components/etc. should be moved into the src/app/ folder.

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

🌐 Ensure your Ionic configuration file has the appropriate type. The project type for v3 is ionic-angular. The project type for v4 is angular. If this value is incorrect, the CLI may invoke the incorrect build scripts.

将以下 ionic.config.json 作为示例:

🌐 See the following ionic.config.json as an example:

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

RxJS 的变化

🌐 RxJS Changes

在 V3 和 V4 之间，RxJS 升级到了 6 版本。这更改了许多操作符和核心 RxJS 函数的导入路径。具体请参见 RxJS 迁移指南。

生命周期事件

🌐 Lifecycle Events

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

🌐 With V4, we're now able to utilize the typical events provided by Angular. But for certain cases, you might want to have access to the events fired when a component has finished animating during its route change. In this case, the ionViewWillEnter, ionViewDidEnter, ionViewWillLeave, and ionViewDidLeave have been ported over from V3. Use these events to coordinate actions with Ionic's own animations system.

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

🌐 Older events like ionViewDidLoad, ionViewCanLeave, and ionViewCanEnter have been removed, and the proper Angular alternatives should be used.

欲了解更多详情，请查看 router-outlet 文档

🌐 For more details, check out the router-outlet docs

覆盖组件

🌐 Overlay Components

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

🌐 In prior versions of Ionic, overlay components such as Loading, Toast, or Alert were created synchronously. In Ionic v4, these components are all created asynchronously. As a result of this, the API is now promise-based.

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

  alert.present();
}

在 v4 中，使用了 Promise：

🌐 In v4, promises are used:

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

🌐 Navigation

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

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

🌐 To provide the platform-specific animations that users are used to, we have created ion-router-outlet for Angular Apps. This behaves in a similar manner to Angular's router-outlet but provides a stack-based navigation (tabs) and animations.

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

🌐 For a detailed explanation in navigation works in a V4 project, check out the Angular navigation guide.

延迟加载

🌐 Lazy Loading

由于导航发生了变化，V4 中延迟加载的机制也发生了变化。

🌐 Since Navigation has changed, the mechanism for lazy loading has also changed in V4.

在 v3 中，典型的延迟加载设置的工作方式如下：

🌐 In v3, a typical lazy loading setup worked like this:

// 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 方法完成的：

🌐 However, in v4, lazy loading is done via the loadChildren method of the Angular router:

// 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 导航指南。

🌐 For a detailed explanation of lazy loading in V4 project, check out the Angular navigation guide.

标记变更

🌐 Markup Changes

自从 v4 转向自定义元素以来，每个组件的标记都有了显著变化。所有这些变化都是为了遵循自定义元素规范，并已在 GitHub 的专用文件中进行了文档记录。

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

从 Ionic 1 更新到 4

🌐 Updating from Ionic 1 to 4

从 Ionic 1 到 Ionic 4：涉及什么？

🌐 Ionic 1 to Ionic 4: What’s Involved?

从 Ionic 1 迁移到 Ionic 4 涉及从 AngularJS（也称为 Angular 1）迁移到 Angular 7+。这些版本之间存在许多架构差异，因此部分应用代码将需要重写。所需的工作量取决于你的应用的复杂性和规模。

🌐 Migrating from Ionic 1 to Ionic 4 involves moving from AngularJS (aka Angular 1) to Angular 7+. There are many architectural differences between these versions, so some of the app code will have to be rewritten. The amount of work involved depends on the complexity and size of your app.

一个好处是，在大多数情况下，你所熟悉和喜爱的 V1 中的 Ionic UI 组件并没有太大变化。

🌐 One upside is that for the most part, the Ionic UI components you know and love from V1 haven’t changed much.

以下是开始升级之前需要查看的一些注意事项：

🌐 Here are some considerations to review before beginning the upgrade:

应用复杂性：自然地，应用越大、越复杂，迁移所需的时间就越长。
框架支持：在2019年，Ionic将发布对React的完整支持。你也可以在没有框架的情况下使用Ionic Framework组件。由于这些尚未准备好用于生产环境，我们建议坚持使用Angular，或者等待其他框架支持可用。
预算和团队组成：迁移项目的时间长短将取决于团队的规模、应用的复杂性以及为过渡分配的时间。

建议策略

🌐 Suggested Strategy

一旦你的开发团队确定了开始迁移的合适时间范围，Ionic 建议对 Ionic 1 应用进行功能冻结并整理代码：修复任何重大漏洞，消除技术债务，并根据需要重新组织。然后，确定要迁移哪些功能以及哪些功能要放弃。

🌐 Once your development team has identified a good time frame for beginning the migration, Ionic recommends feature-freezing the Ionic 1 application and getting the code in order: Fix any major bugs, eliminate tech debt, and reorganize as you see fit. Then, identify which features to migrate over and which to abandon.

一旦 Ionic 1 应用稳定，创建一个新的 Ionic 4 项目。大部分开发团队的注意力应集中在新项目上；Ionic 1 应用中只修复漏洞，以确保过渡尽可能快速和平稳。

🌐 Once the Ionic 1 app is stable, create a new Ionic 4 project. The majority of the dev team’s attention should be given to the new project; only bugs should be fixed in the Ionic 1 app to ensure that the transition happens as quickly and smoothly as possible.

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

🌐 Once the team is comfortable that the Ionic 4 app has become stable and has fulfilled a core set of features, you can then shut down the Ionic 1 app.

从 AngularJS 迁移到 Angular

🌐 Moving From AngularJS to Angular

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

🌐 Please reference official Angular upgrade guide information.

Ionic 变化

🌐 Ionic Changes

我们上述的 Ionic 3 到 Ionic 4 的迁移部分可能会成为一个有用的参考。使用空白起始模板生成一个新的 Ionic 4 项目（参见 Starting an App）。花时间熟悉 Ionic 4 组件。祝你构建愉快！

🌐 Our Ionic 3 to Ionic 4 migration sections above may prove to be a useful reference. Generate a new Ionic 4 project using the blank starter (see Starting an App). Spend time getting familiar with Ionic 4 components. Happy building!

需要帮助？

🌐 Need Assistance?

如果你的团队希望获得迁移方面的帮助，请联系我们！Ionic 提供咨询服务，其中包括 Ionic 4 培训、架构评审和迁移协助。

🌐 If your team would like assistance with the migration, please reach out to us! Ionic offers Advisory Services, which includes Ionic 4 training, architecture reviews, and migration assistance.

从 Ionic 3 更新到 4​

包名称的变化​

项目结构​

RxJS 的变化​

生命周期事件​

覆盖组件​

导航​

延迟加载​

标记变更​

从 Ionic 1 更新到 4​

从 Ionic 1 到 Ionic 4：涉及什么？​

建议策略​

从 AngularJS 迁移到 Angular​

Ionic 变化​

需要帮助？​

目录