更新到 Ionic 4

¥Updating to Ionic 4

从 Ionic 3 更新到 4

¥Updating from Ionic 3 to 4

注意

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

¥This guide assumes that you have already updated your app to the latest version of Ionic 3. If you are using Ionic 1 or 2, Make sure to follow the Updating from Ionic 1 to 4 Guide instead.

重大变化

有关从 Ionic 3 到 Ionic 4 的重大更改的完整列表，请参阅 Ionic 框架存储库中的 重大变更文档。

¥For a complete list of breaking changes from Ionic 3 to Ionic 4, please refer to the breaking changes document in the Ionic Framework repository.

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

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

1. 使用 blank 启动器生成一个新项目（参见 启动应用）

   ¥Generate a new project using the blank starter (see Starting an App)

2. 将任何 Angular 服务从 src/providers 复制到 src/app/services

   ¥Copy any Angular services from src/providers to src/app/services

   • 服务应在 @Injectable() 装饰器中包含 { providedIn: 'root' }。有关详细信息，请参阅 Angular 提供商文档。

     ¥Services should include { providedIn: 'root' } in the @Injectable() decorator. For details, please see Angular provider docs.

3. 复制应用的其他根级项目（管道、组件等），请记住目录结构从 src/components 更改为 src/app/components 等。

   ¥Copy the app's other root-level items (pipes, components, etc) keeping in mind that the directory structure changes from src/components to src/app/components, etc.

4. 将全局 Sass 样式从 src/app/app.scss 复制到 src/global.scss

   ¥Copy global Sass styling from src/app/app.scss to src/global.scss

5. 逐页或逐个功能地复制应用的其余部分，请记住以下几点：

   ¥Copy the rest of the application, page by page or feature by feature, keeping the following items in mind:

   • 模拟 Shadow DOM 默认开启

     ¥Emulated Shadow DOM is turned on by default

   • 页面/组件 Sass 不应再封装在页面/组件标签中，而应使用 Angular 的 @Component 装饰器的 styleUrls 选项

     ¥Page/component Sass should no longer be wrapped in the page/component tag and should use Angular's styleUrls option of the @Component decorator

   • RxJS 已从 v5 更新到 v6（参见 RxJS 的变化）

     ¥RxJS has been updated from v5 to v6 (see RxJS Changes)

   • 某些生命周期钩子应该替换为 Angular 的钩子（参见 生命周期事件）

     ¥Certain lifecycle hooks should be replaced by Angular's hooks (see Lifecycle Events)

   • 可能需要更改标记（可用迁移工具，请参阅 标记变更）

     ¥Markup changes may be required (migration tool available, see Markup Changes)

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

¥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

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

¥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 创建一个新项目 "base"。然后，通过新的项目布局，逐步迁移应用的功能。页面/组件/等。 应移至 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 迁移指南。

¥Between V3 and V4, RxJS was updated to version 6. This changes many of the import paths of operators and core RxJS functions. Please see the RxJS Migration Guide for details.

生命周期事件

¥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 团队在其文档网站上有一个 优秀的导游，其中详细介绍了路由。

¥In V4, navigation received the most changes. Now, instead of using Ionic's own NavController, we integrate with the official Angular Router. This not only provides a consistent routing experience across apps, but is much more dependable. The Angular team has an excellent guide on their docs site that covers the Router in great detail.

为了提供用户习惯的特定于平台的动画，我们为 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 项目中导航工作的详细说明，请查看 角度导航指南。

¥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 项目中延迟加载的详细说明，请查看 角度导航指南。

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

标记变更

¥Markup Changes

自从 v4 迁移到自定义元素以来，每个组件的标记都发生了重大变化。这些更改都是为了遵循自定义元素规范而进行的，并已记录在 GitHub 上的专用文件 中。

¥Since v4 moved to Custom Elements, there's been a significant change to the markup for each component. These changes have all been made to follow the Custom Elements spec, and have been documented in a dedicated file on GitHub.

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

¥To help with these markup changes, we've released a TSLint-based Migration Tool, which detects issues and can even fix some of them automatically.

从 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:

• 应用复杂性：当然，应用越大、越复杂，迁移所需的时间就越长。

  ¥App complexity: Naturally, the larger and more complex the app is, the longer it will take to migrate.

• 框架支持：2019 年，Ionic 将全面支持 React。你还可以使用 Ionic Framework 组件 没有框架。由于这些尚未准备好投入生产，我们建议坚持使用 Angular 或等待其他框架支持可用。

  ¥Framework support: In 2019, Ionic will release full support for React. You can also use Ionic Framework components without a framework. Since these are not production-ready yet, we recommend sticking with Angular or waiting until the other framework support is available.

• 预算和团队构成：迁移项目的长度将根据团队规模、应用的复杂性以及分配给转换的时间量而有所不同。

  ¥Budget and team makeup: The length of a migration project will vary based on the size of your team, the complexity of the app, and the amount of time allotted to make the transition.

建议策略

¥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

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

¥Please reference official Angular upgrade guide information.

Ionic 变化

¥Ionic Changes

我们上面的 Ionic 3 到 Ionic 4 迁移部分可能会被证明是有用的参考。使用空白启动器生成新的 Ionic 4 项目（参见 启动应用）。花时间熟悉 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.