版本：v8

從 Ionic 5 更新至 6

注意

本指南假設您已將應用程式更新至 Ionic 5 的最新版本。在開始本指南之前，請確保您已遵循更新至 Ionic 5 指南。

重大變更

如需從 Ionic 5 至 Ionic 6 的完整重大變更清單，請參閱 Ionic Framework 儲存庫中的重大變更文件。

開始使用

Angular

Ionic 6 支援 Angular 12+。請依照Angular 更新指南更新至最新版本的 Angular。
更新至最新版本的 Ionic 6

npm install @ionic/angular@6

如果您正在使用 Ionic Angular Server，請務必一併更新

npm install @ionic/angular@6 @ionic/angular-server@6

移除任何使用 Config.set() 的情況。請改為在 IonicModule.forRoot() 中設定您的設定。如需更多範例，請參閱Angular 設定文件。
移除任何先前從 @ionic/angular 匯出的 setupConfig 函式的使用。請改為在 IonicModule.forRoot() 中設定您的設定。

React

Ionic 6 支援 React 17+。請更新至最新版本的 React

npm install react@latest react-dom@latest

更新至最新版本的 Ionic 6

npm install @ionic/react@6 @ionic/react-router@6

更新 package.json 的 scripts 物件中的 test 欄位，以包含 transformIgnorePatterns

"scripts": {
  "test": "react-scripts test --transformIgnorePatterns 'node_modules/(?!(@ionic/react|@ionic/react-router|@ionic/core|@stencil/core|ionicons)/)'",
  ...
}

在您的 App 元件檔案中匯入並呼叫 setupIonicReact。如果您也正在使用 setupConfig，請改為將您的設定傳遞至 setupIonicReact

之前

App.tsx
import { setupConfig } from '@ionic/react';

...

setupConfig({
  mode: 'md'
});

之後

App.tsx
import { setupIonicReact } from '@ionic/react';

...

setupIonicReact({
  mode: 'md'
});

注意

即使開發人員沒有設定自訂設定，也必須匯入並呼叫 setupIonicReact。

如需更多範例，請參閱React 設定文件。

將所有控制器匯入從 @ionic/core 更新至 @ionic/core/components。例如，以下是 menuController 的遷移

之前

import { menuController } from '@ionic/core';

之後

import { menuController } from '@ionic/core/components';

Vue

Ionic 6 支援 Vue 3.0.6+。請更新至最新版本的 Vue

npm install vue@3 vue-router@4

對於使用 Vue CLI 的應用程式，請安裝 Vue CLI 5

npm install -g @vue/cli@next

然後，升級所有 Vue CLI 外掛程式

vue upgrade --next

更新至最新版本的 Ionic 6

npm install @ionic/vue@6 @ionic/vue-router@6

將下列 transformIgnorePatterns 新增至 jest.config.js 或 package.json 中的 jest 欄位

jest.config.js
module.exports = {
  ...
  transformIgnorePatterns: ['/node_modules/(?!@ionic/vue|@ionic/vue-router|@ionic/core|@stencil/core|ionicons)']
}

package.json
  {
    ...
    "jest": {
      "transformIgnorePatterns": ["/node_modules/(?!@ionic/vue|@ionic/vue-router|@ionic/core|@stencil/core|ionicons)"]
    }
  }

如需更多資訊，請參閱下方的測試區段。

移除任何先前從 @ionic/vue 匯出的 setupConfig 函式的使用。請改為在安裝 IonicVue 外掛程式時設定您的設定。如需更多範例，請參閱Vue 設定文件。
將 useIonRouter 的 IonRouter 類型重新命名為 UseIonRouterResult。
將 useKeyboard 的 IonKeyboardRef 類型重新命名為 UseKeyboardResult。
重新命名任何覆蓋層事件接聽器以使用新格式

之前

<ion-modal
  :is-open="modalOpenRef"
  @onWillPresent="onModalWillPresentHandler"
  @onDidPresent="onModalDidPresentHandler"
  @onWillDismiss="onModalWillDismissHandler"
  @onDidDismiss="onModalDidDismissHandler"
>
  ...
</ion-modal>

之後

<ion-modal
  :is-open="modalOpenRef"
  @willPresent="onModalWillPresentHandler"
  @didPresent="onModalDidPresentHandler"
  @willDismiss="onModalWillDismissHandler"
  @didDismiss="onModalDidDismissHandler"
>
  ...
</ion-modal>

注意

這適用於 ion-action-sheet、ion-alert、ion-loading、ion-modal、ion-picker、ion-popover 和 ion-toast。

將 ion-router-outlet 傳遞至任何正在使用的 ion-tabs

之前

<ion-tabs>
  <ion-tab-bar slot="bottom"> ... </ion-tab-bar>
</ion-tabs>

<script>
  import { IonTabs, IonTabBar } from '@ionic/vue';
  import { defineComponent } from 'vue';

  export default defineComponent({
    components: { IonTabs, IonTabBar },
  });
</script>

之後

<ion-tabs>
  <ion-router-outlet></ion-router-outlet>
  <ion-tab-bar slot="bottom"> ... </ion-tab-bar>
</ion-tabs>

<script>
  import { IonTabs, IonTabBar, IonRouterOutlet } from '@ionic/vue';
  import { defineComponent } from 'vue';

  export default defineComponent({
    components: { IonTabs, IonTabBar, IonRouterOutlet },
  });
</script>

標籤內的其他路由應重寫為同層路由，而不是子路由

之前

const routes: Array<RouteRecordRaw> = [
  {
    path: '/',
    redirect: '/tabs/tab1'
  },
  {
    path: '/tabs/',
    component: Tabs,
    children: [
      {
        path: '',
        redirect: 'tab1'
      },
      {
        path: 'tab1',
        component: () => import('@/views/Tab1.vue'),
        children: {
          {
            path: 'view',
            component: () => import('@/views/Tab1View.vue')
          }
        }
      },
      {
        path: 'tab2',
        component: () => import('@/views/Tab2.vue')
      },
      {
        path: 'tab3',
        component: () => import('@/views/Tab3.vue')
      }
    ]
  }
]

之後

const routes: Array<RouteRecordRaw> = [
  {
    path: '/',
    redirect: '/tabs/tab1',
  },
  {
    path: '/tabs/',
    component: Tabs,
    children: [
      {
        path: '',
        redirect: 'tab1',
      },
      {
        path: 'tab1',
        component: () => import('@/views/Tab1.vue'),
      },
      {
        path: 'tab1/view',
        component: () => import('@/views/Tab1View.vue'),
      },
      {
        path: 'tab2',
        component: () => import('@/views/Tab2.vue'),
      },
      {
        path: 'tab3',
        component: () => import('@/views/Tab3.vue'),
      },
    ],
  },
];

核心

更新至最新版本的 Ionic 6

npm install @ionic/core@6

更新您的程式碼

日期時間

移除任何 placeholder、pickerOptions、pickerFormat、monthNames、monthShortNames、dayNames 和 dayShortNames 屬性的使用。現在 ion-datetime 會根據裝置上設定的語言和地區，自動格式化元件內顯示的月份名稱、日期名稱和時間。如需更多資訊，請參閱ion-datetime 本地化文件。
移除任何 text 和 placeholder CSS 陰影部分的使用。
移除任何 --padding-bottom、--padding-end、--padding-start、--padding-top 和 --placeholder-color CSS 變數的使用。若要自訂 ion-datetime 的邊距，您可以使用任何 padding CSS 屬性。
移除任何 open 方法的使用。若要以覆蓋層顯示日期時間，請將其放置在 ion-modal 或 ion-popover 元件中。如需更多資訊，請參閱ion-datetime 使用範例。
移除任何 displayFormat 或 displayTimezone 屬性的使用。若要剖析 ionChange 事件酬載中提供的 UTC 字串，我們建議使用date-fns。如需範例，請參閱ion-datetime 剖析日期文件。

注意

如需更多遷移範例，請參閱日期時間遷移範例應用程式。

圖示

Ionic 6 現在隨附 Ionicons 6。請檢閱Ionicons 6 重大變更指南並進行任何必要的變更。

輸入

請確保沒有將 null 作為值傳遞至 placeholder 屬性。我們建議改為使用 undefined。

ion-modal 現在使用 Shadow DOM。請更新任何以 ion-modal 內部為目標的樣式，以使用ion-modal CSS 變數或ion-modal CSS 陰影部分

之前

ion-modal .modal-wrapper {
  /* Any custom styles here */
}

ion-modal ion-backdrop {
  /* Any custom styles here */
}

之後

ion-modal::part(content) {
  /* Any custom styles here */
}

ion-modal::part(backdrop) {
  /* Any custom styles here */
}

ion-popover 現在使用 Shadow DOM。請更新任何以 ion-popover 內部為目標的樣式，以使用ion-popover CSS 變數或ion-popover CSS 陰影部分

之前

ion-popover .popover-arrow {
  /* Any custom styles here */
}

ion-popover ion-backdrop {
  /* Any custom styles here */
}

ion-popover .popover-content {
  /* Any custom styles here */
}

之後

ion-popover::part(arrow) {
  /* Any custom styles here */
}

ion-popover::part(backdrop) {
  /* Any custom styles here */
}

ion-popover::part(content) {
  /* Any custom styles here */
}

單選按鈕

移除任何 RadioChangeEventDetail 介面的使用。

選取

請確保沒有將 null 作為值傳遞至 placeholder 屬性。我們建議改為使用 undefined。

文字區域

請確保沒有將 null 作為值傳遞至 placeholder 屬性。我們建議改為使用 undefined。

瀏覽器支援

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

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

Chrome >=60
Firefox >=63
Edge >=79
Safari >=13
iOS >=13

測試

Ionic 6 現在以 ES Modules 形式發布。所有主要瀏覽器都支援 ES Modules，並帶來開發人員體驗和程式碼維護方面的改進。使用 Jest 進行測試的開發人員將需要更新其 Jest 設定，因為截至 Jest 27，Jest 尚未完全支援 ES Modules。

此更新涉及使用 Babel 將 Ionic 的 ES Modules 編譯為 CommonJS (CJS) 格式，Jest 可以理解的格式。一旦 Jest 支援 ES Modules，此變更將不再必要。有關 Jest 中 ES Modules 支援的更新，請參閱https://github.com/facebook/jest/issues/9430。

如果您是從新的 Ionic 應用程式開始，則我們的入門應用程式中已為您完成此設定。對於那些現有的 Ionic 應用程式，請按照以下步驟操作，使 Jest 能夠與 Ionic 6 一起使用

將 transformIgnorePatterns 欄位新增至您的 Jest 設定，其中包含相關的 Ionic 套件。這通常可以在 jest.config.js 或 package.json 中的 jest 欄位中找到

jest.config.js
module.exports = {
  ...
  transformIgnorePatterns: ['/node_modules/(?!@ionic/core|@stencil/core|ionicons)']
}

package.json
  {
    ...
    "jest": {
      "transformIgnorePatterns": ["/node_modules/(?!@ionic/core|@stencil/core|ionicons)"]
    }
  }

注意

如果您正在使用 Ionic React 或 Ionic Vue，請務必將適當的套件新增至 transformIgnorePatterns 陣列。對於 Ionic React，這包括 @ionic/react 和 @ionic/react-router。對於 Ionic Vue，這包括 @ionic/vue 和 @ionic/vue-router。

對於使用 Create React App (CRA) 的開發人員，目前沒有任何方法可以在 Jest 設定檔中更新 transformIgnorePatterns。這是 CRA 的限制，而不是 Ionic 可以控制的。但是，我們可以將 transformIgnorePatterns 直接傳遞到 react-scripts test 命令中

package.json
"scripts": {
  "test": "react-scripts test --transformIgnorePatterns 'node_modules/(?!(@ionic/react|@ionic/react-router|@ionic/core|@stencil/core|ionicons)/)'",
  ...
}

如果您仍然遇到問題，這裡有一些可以嘗試的方法

驗證 @babel/preset-env 是否包含在您的專案範圍設定中，而不是您的檔案相關設定中。這通常表示在 <project-root>/babel.config.json 中定義 Babel 設定。
如果您的 package.json 檔案中有 browserslist/test 欄位，請確保將其設定為 current node。

需要升級方面的協助嗎？

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

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

從 Ionic 5 更新至 6

開始使用

Angular

React

Vue

核心

更新您的程式碼

日期時間

圖示

輸入

快顯視窗

單選按鈕

選取

文字區域

瀏覽器支援

測試

需要升級方面的協助嗎？

目錄

從 Ionic 5 更新至 6

開始使用​

Angular​

React​

Vue​

核心​

更新您的程式碼​

日期時間​

圖示​

輸入​

模式​

快顯視窗​

單選按鈕​

選取​

文字區域​

瀏覽器支援​

測試​

需要升級方面的協助嗎？​

目錄

開始使用

Angular

React

Vue

核心

更新您的程式碼

日期時間

圖示

輸入

模式

快顯視窗

單選按鈕

選取

文字區域

瀏覽器支援

測試

需要升級方面的協助嗎？