メインコンテンツまでスキップ
バージョン: v8 (beta)

Updating from Ionic 5 to 6

注記

This guide assumes that you have already updated your app to the latest version of Ionic 5. Make sure you have followed the Updating to Ionic 5 Guide before starting this guide.

Breaking Changes

For a complete list of breaking changes from Ionic 5 to Ionic 6, please refer to the breaking changes document in the Ionic Framework repository.

はじめ方

Angular

  1. Ionic 6 は Angular 12+ をサポートしています。 Angular Update Guide に沿って、最新バージョンの Angular に更新します。.
  2. Ionic6 の最新バージョンに更新します。
npm install @ionic/angular@6

Ionic Angular Server を使用している場合は、それも必ず更新してください:

npm install @ionic/angular@6 @ionic/angular-server@6
  1. Remove any usage of Config.set(). Instead, set your config in IonicModule.forRoot(). See the Angular Config Documentation for more examples.
  2. Remove any usage of the setupConfig function previously exported from @ionic/angular. Set your config in IonicModule.forRoot() instead.

React

  1. Ionic 6 は React 17+ をサポートしています。React の最新バージョンに更新します:
npm install react@latest react-dom@latest
  1. Ionic 6 の最新バージョンに更新します:
npm install @ionic/react@6 @ionic/react-router@6
  1. package.jsonscripts オブジェクトにある test フィールドを更新して、 transformIgnorePatterns を含めます:
"scripts": {
"test": "react-scripts test --transformIgnorePatterns 'node_modules/(?!(@ionic/react|@ionic/react-router|@ionic/core|@stencil/core|ionicons)/)'",
...
}
  1. あなたの App コンポーネントで setupIonicReact を呼び出して下さい。もう setupConfig を利用している場合は、 setupIonicReact に置き換えてください:

Before

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

...

setupConfig({
mode: 'md'
});

After

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

...

setupIonicReact({
mode: 'md'
});
注記

開発者は、 setupIonicReact カスタム構成を設定していない場合でも、インポートして呼び出す必要があります。

See the React Config Documentation for more examples.

5.すべてのコントローラのインポートを @ionic/core から @ionic/core/components に更新します。例として、menuController のマイグレーションを紹介します。

Before

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

After

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

Vue

  1. Ionic 6 は Vue 3.0.6+ をサポートしています。Vue の最新バージョンに更新ください。
npm install vue@3 vue-router@4
  1. Vue CLI を使用するアプリの場合は、Vue CLI 5 をインストールします。
npm install -g @vue/cli@next

次に、すべての Vue CLI プラグインをアップグレードします。

vue upgrade --next
  1. Ionic 6 の最新バージョンに更新します。
npm install @ionic/vue@6 @ionic/vue-router@6
  1. package.jsonjest.config.jsjest のどちらかに transformIgnorePatterns を含めます。
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)"]
}
}

詳しくは Testing section below をご覧ください。

  1. Remove any usage of the setupConfig function previously exported from @ionic/vue. Set your config when installing the IonicVue plugin instead. See the Vue Config Documentation for more examples.

  2. useIonRouter で利用してる型 IonRouterUseIonRouterResult に変更してください。

  3. useKeyboard で利用してる型 IonKeyboardRefUseKeyboardResult に変更してください。

  4. すべてのオーバーレイイベントリスナーの名前を変更し、新しいフォーマットを使用するようにします。

Before

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

After

<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 に適用されます。

  1. ion-router-outletion-tabs の中にいれて利用します。

Before

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

After

<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>
  1. タブ内の追加ルートは、子ルートではなく兄弟ルートとして書き直す必要があります。

Before

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')
}
]
}
]

After

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'),
},
],
},
];

Core

  1. Ionic 6 の最新バージョンにアップデートください。
npm install @ionic/core@6

コアのアップデート

Datetime

  1. placeholder, pickerOptions, pickerFormat, monthNames, monthShortNames, dayNames, dayShortNamesプロパティの使用をすべて削除してください。ion-datetime は、デバイスに設定されている言語と地域に応じて、コンポーネント内に表示される月名、日名、時刻を自動的にフォーマットするようになりました。詳細は、ion-datetime Localization Documentation を参照してください。

  2. textplaceholder の CSS シャドウパーツの使用をすべて削除します。

  3. CSS 変数 --padding-bottom, --padding-end, --padding-start, --padding-top, --placeholder-color のすべての使用を削除します。 ion-datetime のパディングをカスタマイズするには、 padding CSS プロパティのいずれかを使用することができます。

  4. open メソッドの使用はすべて削除します。datetime をオーバーレイで表示するには、 ion-modal または ion-popover コンポーネントの中に配置する。詳細は、ion-datetime Usage Examples を参照してください。

  5. displayFormat プロパティまたは displayTimezone プロパティの使用をすべて削除します。ionChange` イベントのペイロードで提供される UTC 文字列をパースするには、date-fns を使用することをお勧めします。例としては、ion-datetime Parsing Dates Documentation を参照してください。

注記

マイグレーション例は Datetime Migration Sample Application をご覧ください。

Icon

Ionic 6 には、Ionicons 6 が同梱されるようになりました。Ionicons 6 Breaking Changes Guide をご確認の上、必要な変更を行なってください。

Input

placeholder プロパティの値として null が渡されていないことを確認してください。代わりに undefined を使用することを推奨します。

ion-modal は Shadow DOM を使用するようになりました。 ion-modal の内部をターゲットとするスタイルは、ion-modal CSS Variables または ion-modal CSS Shadow Parts を使用して更新してください。

Before

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

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

After

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

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

Popover

ion-popover は Shadow DOM を使用するようになりました。 ion-popover の内部をターゲットとするスタイルは、ion-popover CSS Variables または ion-popover CSS Shadow Parts を使用するように更新してください。

Before

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

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

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

After

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

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

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

Radio

RadioChangeEventDetail インターフェースのすべての使用法を削除します。

Select

placeholder プロパティの値として null が渡されていないことを確認してください。代わりに undefined を使用することを推奨します。

Textarea

placeholder プロパティの値として null が渡されていないことを確認してください。代わりに undefined を使用することを推奨します。

ブラウザサポート

Ionic がサポートしているブラウザのリストが変更されました。 ブラウザサポートガイド を確認し、サポートされているブラウザにアプリをデプロイするようにしましょう。

If you have a browserslist or .browserslistrc file, update it with the following content:

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

テスト

Ionic 6 は、ES モジュールとして出荷されるようになりました。ES モジュールは、すべての主要なブラウザでサポートされており、開発者のエクスペリエンスとコードのメンテナンス性を向上させることができます。Jest でテストする開発者は、Jest 27 の時点で Jest が ES Modules を完全にサポートしていないため、Jest の設定を更新する必要があります。

このアップデートでは、Babel を使用して Ionic の ES モジュールを Jest が理解できる CommonJS (CJS) 形式にコンパイルする必要があります。Jest が ES モジュールをサポートするようになれば、この変更は必要なくなります。Jest の ES モジュールサポートに関する最新情報は、https://github.com/facebook/jest/issues/9430 を参照してください。

新しい Ionic アプリを新しく始める場合、この設定はスターターアプリケーションで行われます。既存の Ionic アプリをお持ちの方は、以下の手順で Jest を Ionic 6 で動作させることができます。

  1. Jest の設定に、関連する Ionic パッケージを含む transformIgnorePatterns フィールドを追加します。これは通常 jest.config.js または package.jsonjest フィールドに含まれています。
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 がコントロールできることではありません。しかし、react-scripts test コマンドに直接 transformIgnorePatterns を渡すことはできます。

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

それでも問題が発生する場合は、以下のことを試してみてください。

  1. @babel/preset-envfile-relative configuration ではなく、 project-wide configuration に含まれていることを確認します。これは通常、 <project-root>/babel.config.json で Babel 設定を定義することを意味します。

  2. package.json ファイルに browserslist/test フィールドがある場合、それが current node に設定されていることを確認してください。

アップグレートへの助けが必要?

Ionic 6 Breaking Changes Guide を必ずご覧ください。デフォルトのプロパティと CSS 変数の値について、開発者が知っておくべき変更がいくつかありました。このページでは、ユーザーによる操作が必要な変更点のみを掲載しています。

アップグレードに助けが必要な場合、 Ionic Forum にスレッドを立ててください。