Version: v8

Ionic 7 から 8 へのアップデート

note

このガイドでは、アプリを Ionic 7 の最新バージョンにアップデート済みであることを前提としています。このガイドを始める前に、Ionic 7 へのアップグレードガイドに従っていることを確認してください。

Breaking Changes

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

Ionic Angular Server と Ionic Angular Toolkit を使用している場合は、それらもアップデートしてください：

npm install @ionic/angular@next @ionic/angular-server@next @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@next @ionic/react-router@next

Vue

Ionic 7 は Vue 3.0.6+をサポートしています。最新バージョンの Vue にアップデートしてください：

npm install vue@latest vue-router@latest

Ionic 8 の最新バージョンにアップデートする：

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

Core

Ionic 8 の最新バージョンにアップデートする：

npm install @ionic/core@next

推奨の変更

お手持ちのアプリケーションは引き続き動作するため、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] に変更することで移行できます。

Example:

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

テキストカラーの --ion-color-step-[number] の使用は、トークンの名前を --ion-text-color-step-[number] に変更し、1000 から数値を引くことで移行できます。

Example:

button {
- color: var(--ion-color-step-400);
+ 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 ファイルを最初にインポートすることをお勧めします：

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

チェックボックス

チェックボックスの残りのインスタンスを、最新のフォーム制御構文を使用するように移行します。さらに、レガシーなフォームコントロール構文は削除されたので、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 フォーラムにスレッドを投稿してください。

Ionic 7 から 8 へのアップデート

はじめ方​

Angular​

React​

Vue​

Core​

推奨の変更​

Light Palette​

Dark Palette​

ステップカラートークン​

ダイナミックフォント​

(Angular Only) angular.json CSS を import する順番​

必要な変更​

ブラウザーサポート​

チェックボックス​

Input​

Item​

Nav​

Picker​

Toast​

Radio​

Select​

Textarea​

Toggle​

アップグレードの手助けが必要ですか？​

Contents