更新至 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. 逐頁或逐功能地複製應用程式的其餘部分，請記住以下項目
   • 預設已開啟模擬陰影 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 中，同步建立載入、快顯通知或警示等覆蓋層元件。在 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());
}

// 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 團隊在其文件網站上提供了關於 Router 的絕佳指南，其中詳細介紹了 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 已移至自訂元素，因此每個元件的標記都發生了重大變更。所有這些變更都是為了遵循自訂元素規範而進行的，並且已記錄在 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 培訓、架構審查和遷移協助。