跳至主要內容
版本：v8

從 Ionic 7 更新至 8

注意

本指南假設您已將應用程式更新至 Ionic 7 的最新版本。在開始本指南之前，請務必遵循升級至 Ionic 7 指南。

重大變更

如需從 Ionic 7 到 Ionic 8 的完整重大變更清單，請參閱 Ionic Framework 存放庫中的重大變更文件。

開始使用​

Angular​

  1. Ionic 8 支援 Angular 16+。請遵循Angular 更新指南更新至最新版本的 Angular。

  2. 更新至最新版本的 Ionic 8

npm install @ionic/angular@latest

如果您使用 Ionic Angular Server 和 Ionic Angular Toolkit，請務必同時更新這些工具

npm install @ionic/angular@latest @ionic/angular-server@latest @ionic/angular-toolkit@11

注意：@ionic/angular-toolkit@11 需要至少 Angular 17。如果您仍在使用 Angular 16，則可能只想更新至 @ionic/angular-toolkit@10。

  1. 將任何從 @ionic/angular 匯入的 IonBackButtonDelegate 更新為改為從 @ionic/angular 匯入 IonBackButton。

React​

  1. Ionic 8 支援 React 17+。更新至最新版本的 React
npm install react@17 react-dom@17
  1. 更新至最新版本的 Ionic 8
npm install @ionic/react@8 @ionic/react-router@8

Vue​

  1. Ionic 8 支援 Vue 3.0.6+。更新至最新版本的 Vue
npm install vue@^3.0.6 vue-router@^3.0.6
  1. 更新至最新版本的 Ionic 8
npm install @ionic/vue@8 @ionic/vue-router@8

核心​

  1. 更新至最新版本的 Ionic 8
npm install @ionic/core@8

以下變更不是更新至 Ionic 8 所必需的，因為您的應用程式將繼續運作。但是，我們建議進行以下變更，以確保您可以使用 Ionic 8 中的新功能。

淺色調色盤​

先前的版本在 theme/variables.scss 中定義了一組淺色調色盤的預設色彩變數

/** Ionic CSS Variables **/
:root {
  /** primary **/
  --ion-color-primary: #3880ff;
  --ion-color-primary-rgb: 56, 128, 255;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  /* ... */
}

在 Ionic Framework 版本 8 中，只要匯入 core.css，就會包含這些色彩變數。應移除 theme/variables.scss 中定義的色彩變數，以避免覆寫匯入的預設變數，並確保應用程式始終使用最新的調色盤。

正在自訂此調色盤的開發人員可以繼續保留自訂變數值，但應移除任何使用預設值的變數。

您可以在Ionic v8 公告中閱讀更多有關新調色盤的資訊。

深色調色盤​

在先前的版本中，建議以以下方式定義深色調色盤

@media (prefers-color-scheme: dark) {
  body {
    /* global app variables */
  }

  .ios body {
    /* global ios app variables */
  }

  .md body {
    /* global md app variables */
  }
}

在 Ionic Framework 版本 8 中，深色調色盤透過可以匯入的 css 檔案來散發。以下是在 Angular 中匯入深色調色盤檔案的範例

/* @import '@ionic/angular/css/palettes/dark.always.css'; */
/* @import "@ionic/angular/css/palettes/dark.class.css"; */
@import '@ionic/angular/css/palettes/dark.system.css';

深色調色盤現在會套用至 :root 選取器，而不是 body 選取器。:root 選取器代表 <html> 元素，且與選取器 html 相同，但其特異性較高。

雖然遷移以包含新的深色調色盤檔案不太可能導致重大變更，但如果在 body 元素上設定自訂 CSS 變數，這些新的選取器可能會導致意外的覆寫。我們建議更新任何將全域應用程式變數設定為以 :root 選取器為目標的執行個體。

如需有關新深色調色盤檔案的詳細資訊，請參閱深色模式文件。

步階色彩權杖​

為了在 Ionic 8 中更好地支援高對比度調色盤，已為文字和背景色彩引入了單獨的步階色彩權杖。先前，文字和背景色彩都是由一組 --ion-color-step-[number] 權杖控制。

使用上面提到新匯入的深色調色盤也會匯入這些新的步階色彩權杖。但是，開發人員將需要更新應用程式中任何手動定義的步階色彩權杖。

背景色彩的 --ion-color-step-[number] 用法可以透過將權杖重新命名為 --ion-background-color-step-[number] 來遷移。

之前:

button { background: var(--ion-color-step-400); }

之後:

button { background: var(--ion-background-color-step-400); }

文字色彩的 --ion-color-step-[number] 用法可以透過將權杖重新命名為 --ion-text-color-step-[number] 並從 1000 中減去該數字來遷移。

之前:

button { color: var(--ion-color-step-400); }

之後:

button { color: var(--ion-text-color-step-600); /* 1000 - 400 = 600 */ }

步階色彩產生器已更新為產生文字和背景色彩步階變數。

動態字體​

core.css 檔案已更新為預設啟用動態字體縮放。

--ion-default-dynamic-font 變數已移除，並取代為 --ion-dynamic-font。

先前選擇透過在其全域樣式表中啟用動態字體縮放的開發人員，可以透過移除其自訂 CSS 來還原為預設設定。如此一來，他們的應用程式將像以前一樣順利地繼續使用動態字體縮放。必須注意，應避免變更 html 元素的字型大小，因為它可能會中斷動態字體縮放的正常運作。

想要停用動態字體縮放的開發人員可以在其全域樣式表中設定 --ion-dynamic-font: initial;。但是，不建議這樣做，因為它可能會為依賴放大字型大小的使用者引入協助工具方面的挑戰。

如需有關動態字體的詳細資訊，請參閱動態字體縮放文件。

(僅限 Angular) angular.json CSS 匯入順序​

angular.json 檔案目前在匯入 src/global.scss 之前匯入 src/theme/variables.scss。在自訂新的深色調色盤變更時，這可能會導致套用不正確的樣式。

我們建議先匯入 src/global.scss 檔案

之前:

  "styles": ["src/theme/variables.scss", "src/global.scss"],

之後:

  "styles": ["src/global.scss", "src/theme/variables.scss"],

必要的變更​

瀏覽器支援​

Ionic 支援的瀏覽器清單已變更。請檢閱瀏覽器支援指南，以確保您將應用程式部署到受支援的瀏覽器。

如果您有 browserslist 或 .browserslistrc 檔案，請使用以下內容更新它

Chrome >=89
ChromeAndroid >=89
Firefox >=75
Edge >=89
Safari >=15
iOS >=15

核取方塊​

  1. 遷移 Checkbox 的任何剩餘執行個體以使用現代表單控制項語法。此外，請移除任何對 legacy 屬性的使用，因為已移除舊版表單控制項語法。

輸入​

  1. 移除任何對 size 屬性的使用。應使用 CSS 來指定輸入的可見寬度。
  2. 移除任何對 accept 屬性的使用。
  3. 遷移所有剩餘的 Input 實例，以使用現代表單控制語法。此外，移除所有使用 legacy 屬性的地方，因為舊式的表單控制語法已移除。

項目​

  1. 移除所有使用 counter 或 counterFormatter 屬性的地方。請改用 ion-input 和 ion-textarea 上同名的屬性。
  2. 移除所有使用 helper 或 error 插槽的地方。請改用 ion-input 和 ion-textarea 上的 helperText 和 errorText 屬性。
  3. 移除所有使用 fill 或 shape 屬性的地方。請改用 ion-input、ion-textarea 和 ion-select 上同名的屬性。
  1. 更新所有使用 getLength 的地方，在使用回傳值之前，先 await 呼叫，因為此方法現在回傳 Promise<number> 而不是 number。

選擇器​

  1. Ionic 8 現在提供內嵌的 ion-picker 元件。希望繼續使用舊式選擇器的開發人員應將所有 ion-picker 的用法更新為 ion-picker-legacy。pickerController 的 import 保持不變。請注意，ion-picker-legacy 元件將在 Ionic 未來的重大版本中移除。有關使用資訊，請參閱選擇器文件。

快顯訊息​

  1. 移除 ToastButton 中所有使用 cssClass 屬性的地方。應改用 button CSS 陰影部分。

單選按鈕​

  1. 遷移所有剩餘的 Radio 實例，以使用現代表單控制語法。此外，移除所有使用 legacy 屬性的地方，因為舊式的表單控制語法已移除。

選取器​

  1. 遷移所有剩餘的 Select 實例，以使用現代表單控制語法。此外，移除所有使用 legacy 屬性的地方，因為舊式的表單控制語法已移除。

文字區域​

  1. 遷移所有剩餘的 Textarea 實例，以使用現代表單控制語法。此外，移除所有使用 legacy 屬性的地方，因為舊式的表單控制語法已移除。

切換開關​

  1. 遷移所有剩餘的 Toggle 實例，以使用現代表單控制語法。此外，移除所有使用 legacy 屬性的地方，因為舊式的表單控制語法已移除。

需要升級協助嗎？​

請務必查看Ionic 8 重大變更指南。預設屬性和 CSS 變數值有一些變更，開發人員可能需要注意。此頁面上僅列出需要使用者操作的重大變更。

如果您需要升級方面的協助，請在 Ionic 論壇上發文。

目錄

編輯此頁面