Ionic 7 から 8 へのアップデート
このガイドでは、アプリを Ionic 7 の最新バージョンにアップデート済みであることを前提と しています。このガイドを始める前に、Ionic 7 へのアップグレードガイドに従っていることを確認してください。
Ionic 7 から Ionic 8 への変更点の完全なリストについては、Ionic Framework リポジトリの変更点ドキュメントを参照してください。
はじめ方
Angular
-
Ionic 8 は Angular 16+をサポートしています。Angular Update Guide](https://update.angular.io/)に従って、Angularの最新バージョンにアップデートしてください。
-
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
にアップデートしてください。
@ionic/angular
からインポートしたIonBackButtonDelegate
の代わりにIonBackButton
をインポートするように更新する。
React
- Ionic 8 は React 17+をサポートしています。最新バージョンの React にアップデートしてください:
npm install react@latest react-dom@latest
- Ionic 8 の最新バージョンにアップデートする:
npm install @ionic/react@latest @ionic/react-router@latest
Vue
- Ionic 7 は Vue 3.0.6+をサポートしています。最新バージョンの Vue にアップデートしてください:
npm install vue@latest vue-router@latest
- Ionic 8 の最新バージョンにアップデートする:
npm install @ionic/vue@latest @ionic/vue-router@latest
Core
- Ionic 8 の最新バージョンにアップデートする:
npm install @ionic/core@latest
推奨の変更
お手持ちのアプリケーションは引き続き動作するため、Ionic 8 へのアップデートに以下の変更は必要ありません。ただし、Ionic 8 の新機能を確実にご利用いただくために、以下の変更を行うことをお勧めします。
Light Palette
以前のバージョンでは、 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 のお知らせをご覧ください。
Dark Palette
In previous versions, it was recommended to define the dark palette in the following way:
@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';
ダークパレットは body
セレクタの代わりに :root
セレクタに適用されるようになりました。セレクタ :root
は <html>
要素を表し、セレクタ html
と同じですが、特異性が高くなります。
新しいダークパレットファイルをインクルードするように移行しても大きな変更はありませんが、カスタム CSS 変数がbody
要素に設定されている場合、これらの新しいセレクタが予期せぬオーバーライドを引き起こす可能性があります。グローバルなアプリケーション変数が設定されている場合は、代わりに :root
セレクタをターゲットとするように更新することをお勧めします。
新しいダークパレットファイルの詳細については、ダークモードドキュメントを参照してください。
ステップカラートークン
Ionic 8 のハイコントラストパレットをよりよくサポートするために、テキストと背景色に別々のステップカラートークンが導入されました。これまでは、文字色と背景色の両方を 1 つのトークンである --ion-color-step-[number]
トークンで制御していました。
上記の新しくインポートされたダークパレットを使用すると、これらの新しいステップカラートークンもインポートされます。しかし、開発者はアプリケーション内で手動で定義されたステップカラートークンを更新する必要があります。
背景色に対する --ion-color-step-[number]
の使用は、トークンの名前を --ion-background-color-step-[number]
に変更することで移行できます。
Before:
button { background: var(--ion-color-step-400); }
After:
button { background: var(--ion-background-color-step-400); }
テキストカラーの --ion-color-step-[number]
の使用は、トークンの名前を --ion-text-color-step-[number]
に変更し、1000 から数値を引くことで移行できます。
Before:
button { color: var(--ion-color-step-400); }
After:
button { color: var(--ion-text-color-step-600); /* 1000 - 400 = 600 */ }
The stepped color generator has been updated to generate text and background color stepped variables.
ダイナミックフォント
core.css
ファイルが更新され、デフォルトでダイナミックフォントスケーリングが有効になりました。
ion-default-dynamic-font
変数が削除され、--ion-dynamic-font
に置き換えられました。
これまでグローバルスタイルシートでダイナミックフォントスケーリングを有効にしていた開発者は、カスタム CSS を削除することでデフォルトの設定に戻すことができます。そうすることで、アプリケーションは以前のようにシームレスにダイナミック・フォント・スケーリングを利用し続けることができます。ダイナミック・フォント・スケーリングの適切な機能を妨げる可能性があるため、html 要素のフォント・サイズを変更することは避けるべきです。
ダイナミック・フォント・スケーリングを無効にしたい開発者は、グローバル・スタイルシートで--ion-dynamic-font: initial;
を設定することができます。しかし、拡大されたフォントサイズに依存しているユーザーにとってアクセシビリティ上の問題が生じる可能性があるため、これは推奨されません。
ダイナミックフォントの詳細については、Dynamic Font Scaling documentationを参照してください。
(Angular Only) angular.json
CSS を import する順番
現在 angular.json
ファイルは src/global.scss
をインポートする前に src/theme/variables.scss
をインポートしています。このため、新しいDark Paletteの変更をカスタマイズする際に、正しくないスタイルが適用される可能性があります。
代わりに src/global.scss
ファイルを最初にインポートすることをお勧めします:
Before:
"styles": ["src/theme/variables.scss", "src/global.scss"],
After:
"styles": ["src/global.scss", "src/theme/variables.scss"],
必要な変更
ブラウザーサポート
Ionic がサポートするブラウザーのリストが変更されました。 ブラウザサポートガイド を確認し、サポートされているブラウザにアプリをデプロイしていることを確認してください。
browserslist
または .browserslistrc
ファイルがある場合は、以下の内容で更新してください:
Chrome >=89
ChromeAndroid >=89
Firefox >=75
Edge >=89
Safari >=15
iOS >=15
チェックボックス
- チェックボックスの残りのインスタンスを、最新のフォーム制御構文 を使用するように移行します。さらに、レガシーなフォームコントロール構文は削除されたので、
legacy
プロパティの使用をすべて削除します。
Input
size
プロパティを削除してください。代わりに CSS で入力の可視幅を指定するようになりました。accept
プロパティを削除する。- モダンなフォームコントロール構文を使用するように、Input の残りのインスタンスを移行します。さらに、レガシーなフォームコントロール構文は削除されたので、
legacy
プロパティの使用をすべて削除します。
Item
counter
またはcounterFormatter
プロパティを削除します。代わりにion-input
とion-textarea
の同じ名前のプロパティを使用します。helper
スロットまたはerror
スロットを削除します。代わりにion-input
とion-textarea
のhelperText
プロパティとerrorText
プロパティを使用します。fill
またはshape
プロパティを削除します。代わりにion-input
、ion-textarea
、ion-select
で同じ名前のプロパティを使用します。
Nav
- このメソッドは
number
の代わりにPromise<number>
を返すようになったので、getLength
を使用している場合は、戻り値にアクセスする前にawait
するように更新してください。
Picker
- Ionic 8 にはインラインの
ion-picker
コンポーネントが同梱されるようになりました。レガシーピッカーを引き続き使用したい開発者は、ion-picker
を使用している場合はion-picker-legacy
に更新してください。pickerController
インポートに変更はありません。なお、ion-picker-legacy
コンポーネントは Ionic の次期メジャーリリースで削除される予定です。使用方法については、Picker documentation を参照してください。
Toast
ToastButton
からcssClass
プロパティを削除します。代わりにbutton
CSS Shadow Part を使用します。
Radio
- Radio の残りのインスタンスを最新のフォーム制御構文を使用するように移行する。さらに、レガシーなフォーム制御構文は削除されたので、
legacy
プロパティの使用をすべて削除します
Select
- Select の残りのインスタンスを最新のフォームコントロール構文を使用するように移行します。さらに、レガシーなフォーム制御構文は削除されたので、
legacy
プロパティの使用をすべて削除します
Textarea
- 残っている Textarea のインスタンスを modern form control syntax を使うように移行します。さらに、レガシーなフォーム制御構文は削除されたので、
legacy
プロパティの使用をすべて削除します。
Toggle
- 残っている Toggle のインスタンスを、モダンなフォームコントロール構文 を使用するように移行します。さらに、レガシーなフォーム制御構文は削除されたので、
legacy
プロパティの使用をすべて削除します。
アップグレードの手助けが必要ですか?
必ずIonic 8 Breaking Changes Guideをご覧ください。デフォルトのプロパティと CSS Variable の値に、開発者が注意する必要がある変更がいくつかありました。このページでは、ユーザーアクションが必要な変更のみをリストアップしています。
アップグレードのヘルプが必要な場合は、Ionic フォーラムにスレッドを投稿してください。