バージョン: v8

ion-toast

トーストは、最近のアプリケーションで一般的に使用される控えめな通知です。操作に関するフィードバックを提供したり、システムメッセージを表示するために使用できます。トーストはアプリのコンテンツの上に表示され、アプリによって破棄されて、アプリとのユーザーインタラクションを再開できます。

インライントースト（推奨）

ion-toast は、テンプレートにコンポーネントを直接記述することで使用できます。これにより、トーストを表示するために必要なハンドラーの数を減らすことができます。

`isOpen` の使用

ion-toast の isOpen プロパティを使用すると、開発者はアプリケーションの状態からトーストの表示状態を制御できます。つまり、isOpen が true に設定されている場合はトーストが表示され、isOpen が false に設定されている場合はトーストが破棄されます。

isOpen は一方向のデータバインディングを使用します。つまり、トーストが破棄されても自動的に false に設定されることはありません。開発者は ionToastDidDismiss または didDismiss イベントをリッスンし、isOpen を false に設定する必要があります。この理由は、ion-toast の内部がアプリケーションの状態と密接に結合するのを防ぐためです。一方向のデータバインディングを使用すると、トーストはリアクティブ変数から提供されるブール値のみを考慮する必要があります。双方向のデータバインディングでは、トーストはブール値とリアクティブ変数自体の存在の両方を考慮する必要があります。これにより、非決定的な動作が発生し、アプリケーションのデバッグが困難になる可能性があります。

コントローラートースト

破棄

トーストは控えめな通知として意図されており、ユーザーを中断すべきではありません。その結果、トーストを破棄するためにユーザーインタラクションを必須にするべきではありません。

トーストは、表示するミリ秒数をトーストオプションの duration に渡すことで、特定の時間後に自動的に破棄できます。ロールが "cancel" のボタンを追加すると、そのボタンでトーストが破棄されます。作成後にトーストを破棄するには、インスタンスの dismiss() メソッドを呼び出します。

ハードウェアの戻るボタンを押しても、トーストはユーザーを中断しないように設計されているため、破棄されません。

次の例では、buttons プロパティを使用して、クリック時に自動的にトーストを破棄するボタンを追加する方法と、破棄イベントの role を収集する方法を示します。

コンソール

上記の例からログに記録されたコンソールメッセージがここに表示されます。

配置

トーストは、ビューポートの上部、下部、または中央に配置できます。位置は作成時に渡すことができます。可能な値は、top、bottom、middle です。位置が指定されていない場合、トーストはビューポートの下部に表示されます。

相対配置

ヘッダー、フッター、または FAB などのナビゲーション要素とともにトーストが表示される場合、トーストはデフォルトでこれらの要素と重なる可能性があります。これは、要素参照または ID のいずれかを受け取る positionAnchor プロパティを使用して修正できます。トーストは、選択した要素を基準に配置され、position="top" を使用する場合はその下に、position="bottom" を使用する場合はその上に表示されます。position="middle" を使用する場合、positionAnchor プロパティは無視されます。

スワイプで破棄

トーストは、swipeGesture プロパティを使用してスワイプで破棄できます。この機能は位置を認識しており、ユーザーがスワイプする必要がある方向は、position プロパティの値に基づいて変わることを意味します。また、ユーザーがスワイプする必要がある距離は、positionAnchor プロパティの影響を受ける可能性があります。

レイアウト

トースト内のボタンコンテナは、メッセージと同じ行に表示するか、layout プロパティを使用して別の行に積み重ねて表示できます。スタックレイアウトは、長いテキスト値を持つボタンで使用する必要があります。また、スタックトーストレイアウトのボタンは、start または end のいずれかの side 値を使用できますが、両方を使用することはできません。

アイコン

アイコンは、トースト内のコンテンツの隣に追加できます。一般に、トーストのアイコンは、ユーザーの注意を引いたり、トーストの優先度を上げたりするのではなく、追加のスタイルやコンテキストを追加するために使用する必要があります。ユーザーに優先度の高いメッセージを伝えたり、応答を保証したりする場合は、代わりにアラートを使用することをお勧めします。

テーマ

アクセシビリティ

フォーカスの管理

トーストは控えめな通知として意図されており、ユーザーを中断するように設計されていません。トーストを破棄するためにユーザーインタラクションを必須にするべきではありません。その結果、トーストが表示されてもフォーカスが自動的にトーストに移動することはありません。

スクリーンリーダー

トーストは、スクリーンリーダーによるアクセシビリティを確保するために、ariaプロパティを設定します。ただし、これらのプロパティが十分に説明的でない場合や、アプリでのトーストの使用方法と一致しない場合は、上書きできます。

役割

ion-toast は、内部の .toast-content 要素に role="status" および aria-live="polite" を設定します。これにより、スクリーンリーダーはトーストのメッセージとヘッダーのみをアナウンスするようになります。トーストが表示されたとき、ボタンとアイコンはアナウンスされません。

aria-live により、スクリーンリーダーはトーストの内容が更新されたときにアナウンスします。ただし、属性が 'polite' に設定されているため、スクリーンリーダーは現在のタスクを中断しません。

トーストは控えめな通知として意図されているため、aria-live は決して "assertive" に設定しないでください。開発者が重要なメッセージでユーザーを中断する必要がある場合は、アラートを使用することをお勧めします。

トーストボタンの説明

テキストを含むボタンは、操作されたときにスクリーンリーダーによって読み上げられます。ボタンにアイコンのみが含まれている場合、または既存のテキスト以外の説明が必要な場合は、ボタンの htmlAttributes プロパティに aria-label を渡すことによって、ボタンにラベルを割り当てる必要があります。

Angular
Javascript
React
Vue

const toast = await this.toastController.create({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

const toast = await this.toastController.create({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

useIonToast({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

const toast = await toastController.create({
  header: 'Header',
  buttons: [
    {
      icon: 'close',
      htmlAttributes: {
        'aria-label': 'close',
      },
    },
  ],
});

ヒント

これは完全なリストではありませんが、トーストを使用する際に従うべきいくつかのガイドラインを次に示します。

トーストを閉じるためにユーザーの操作を要求しないでください。たとえば、トーストに「閉じる」ボタンがあるのは問題ありませんが、トーストはタイムアウト期間後に自動的に閉じられる必要もあります。通知にユーザーの操作が必要な場合は、代わりにアラートの使用を検討してください。
長いメッセージを含むトーストの場合は、ユーザーがトーストの内容を読むのに十分な時間を確保するために、duration プロパティを調整することを検討してください。
トーストにボタンを追加する場合は、各ボタンに関連付けられたアクションを完了するための代替手段を常に提供してください。これにより、ユーザーが読み終わる前にトーストが閉じられた場合でも、トーストに表示されたアクションを完了できることが保証されます。
モーダルなどの別のオーバーレイ内からボタン付きのトーストを表示することは避けてください。モーダルなどのオーバーレイは、フォーカストラップを実装しており、スクリーンリーダーがフォーカスをトーストに移動してアクションを完了することを妨げます。トーストはスクリーンリーダーによってアナウンスされるため、ユーザーにとって混乱を招く可能性があります。これは、各ボタンに関連付けられたアクションを完了するための代替手段が実装されている場合でも当てはまります。トーストを使用する代わりに、フォーカストラップされたモーダル内にライブリージョンを作成することを検討してください。

インターフェース

ToastButton

interface ToastButton {
  text?: string;
  icon?: string;
  side?: 'start' | 'end';
  role?: 'cancel' | string;
  cssClass?: string | string[];
  htmlAttributes?: { [key: string]: any };
  handler?: () => boolean | void | Promise<boolean | void>;
}

ToastOptions

interface ToastOptions {
  header?: string;
  message?: string | IonicSafeString;
  cssClass?: string | string[];
  duration?: number;
  buttons?: (ToastButton | string)[];
  position?: 'top' | 'bottom' | 'middle';
  translucent?: boolean;
  animated?: boolean;
  icon?: string;
  htmlAttributes?: { [key: string]: any };

  color?: Color;
  mode?: Mode;
  keyboardClose?: boolean;
  id?: string;

  enterAnimation?: AnimationBuilder;
  leaveAnimation?: AnimationBuilder;
}

プロパティ

animated

説明	`true` の場合、トーストはアニメーション化されます。
属性	`animated`
型	`boolean`
デフォルト	`true`

buttons

説明	トーストのボタンの配列。
属性	`undefined`
型	`(string ｜ ToastButton)[] ｜ undefined`
デフォルト	`undefined`

color

説明	アプリケーションのカラーパレットから使用する色。デフォルトのオプションは、`"primary"`、`"secondary"`、`"tertiary"`、`"success"`、`"warning"`、`"danger"`、`"light"`、`"medium"`、および `"dark"` です。色の詳細については、テーマ設定を参照してください。
属性	`color`
型	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined`
デフォルト	`undefined`

cssClass

説明	カスタムCSSを適用するための追加クラス。複数のクラスが指定されている場合は、スペースで区切る必要があります。
属性	`css-class`
型	`string ｜ string[] ｜ undefined`
デフォルト	`undefined`

duration

説明	トーストを非表示にするまで待機するミリ秒数。デフォルトでは、`dismiss()` が呼び出されるまで表示されます。
属性	`duration`
型	`number`
デフォルト	`config.getNumber('toastDuration', 0)`

enterAnimation

説明	トーストが表示されるときに使用するアニメーション。
属性	`undefined`
型	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
デフォルト	`undefined`

説明	トーストに表示されるヘッダー。
属性	`header`
型	`string ｜ undefined`
デフォルト	`undefined`

htmlAttributes

説明	トーストに渡す追加属性。
属性	`undefined`
型	`undefined ｜ { [key: string]: any; }`
デフォルト	`undefined`

icon

説明	表示するアイコンの名前、または有効なSVGファイルへのパス。`ion-icon` を参照してください。 https://ionic.io/ionicons
属性	`icon`
型	`string ｜ undefined`
デフォルト	`undefined`

isOpen

説明	`true` の場合、トーストが開きます。`false` の場合、トーストが閉じます。プレゼンテーションをより細かく制御する必要がある場合はこれを使用してください。それ以外の場合は、toastControllerまたは `trigger` プロパティを使用してください。注意：トーストが閉じるときに `isOpen` が自動的に `false` に設定されることはありません。コードでそれを設定する必要があります。
属性	`is-open`
型	`boolean`
デフォルト	`false`

keyboardClose

説明	`true` の場合、オーバーレイが表示されるときにキーボードが自動的に閉じられます。
属性	`keyboard-close`
型	`boolean`
デフォルト	`false`

layout

説明	トースト内のメッセージとボタンのレイアウト方法を定義します。「baseline」：メッセージとボタンは同じ行に表示されます。メッセージテキストはメッセージコンテナ内で折り返すことができます。「stacked」：ボタンコンテナとメッセージが互いに積み重ねられます。ボタンに長いテキストがある場合はこれを使用してください。
属性	`layout`
型	`"baseline" ｜ "stacked"`
デフォルト	`'baseline'`

leaveAnimation

説明	トーストが閉じられるときに使用するアニメーション。
属性	`undefined`
型	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
デフォルト	`undefined`

message

説明	トーストに表示されるメッセージ。このプロパティはカスタムHTMLを文字列として受け入れます。コンテンツはデフォルトでプレーンテキストとして解析されます。カスタムHTMLを使用する前に、Ionic構成で `innerHTMLTemplatesEnabled` を `true` に設定する必要があります。
属性	`message`
型	`IonicSafeString ｜ string ｜ undefined`
デフォルト	`undefined`

mode

説明	モードは、使用するプラットフォームスタイルを決定します。
属性	`mode`
型	`"ios" ｜ "md"`
デフォルト	`undefined`

position

説明	画面上のトーストの開始位置。`positionAnchor` プロパティを使用してさらに調整できます。
属性	`position`
型	`"bottom" ｜ "middle" ｜ "top"`
デフォルト	`'bottom'`

positionAnchor

説明	トーストの位置のアンカーとなる要素。直接参照または要素のIDとして設定できます。`position="bottom"` の場合、トーストは選択した要素の上に配置されます。`position="top"` の場合、トーストは選択した要素の下に配置されます。`position="middle"` の場合、`positionAnchor` の値は無視されます。
属性	`position-anchor`
型	`HTMLElement ｜ string ｜ undefined`
デフォルト	`undefined`

swipeGesture

説明	「vertical」に設定すると、トーストはスワイプジェスチャで閉じることができます。スワイプ方向は、`position` プロパティの値によって決定されます。`top`：トーストはスワイプアップして閉じることができます。`bottom`：トーストはスワイプダウンして閉じることができます。`middle`：トーストはスワイプアップまたはダウンして閉じることができます。
属性	`swipe-gesture`
型	`"vertical" ｜ undefined`
デフォルト	`undefined`

translucent

説明	`true` の場合、トーストは半透明になります。モードが `"ios"` で、デバイスが`backdrop-filter`をサポートしている場合にのみ適用されます。
属性	`translucent`
型	`boolean`
デフォルト	`false`

trigger

説明	クリック時にトーストを開くトリガー要素に対応するID。
属性	`trigger`
型	`string ｜ undefined`
デフォルト	`undefined`

イベント

名前	説明	バブル
`didDismiss`	トーストが閉じた後に発生します。ionToastDidDismissの省略形。	`true`
`didPresent`	トーストが表示された後に発生します。ionToastWillDismissの省略形。	`true`
`ionToastDidDismiss`	トーストが閉じた後に発生します。	`true`
`ionToastDidPresent`	トーストが表示された後に発生します。	`true`
`ionToastWillDismiss`	トーストが閉じられる前に発生します。	`true`
`ionToastWillPresent`	トーストが表示される前に発生します。	`true`
`willDismiss`	トーストが閉じられる前に発生します。ionToastWillDismissの省略形。	`true`
`willPresent`	トーストが表示される前に発生します。ionToastWillPresentの省略形。	`true`

メソッド

dismiss

説明	トーストオーバーレイが表示された後に閉じます。
署名	`dismiss(data?: any, role?: string) => Promise<boolean>`

onDidDismiss

説明	トーストが閉じたときに解決されるプロミスを返します。
署名	`onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

onWillDismiss

説明	トーストが閉じられるときに解決されるプロミスを返します。
署名	`onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

present

説明	トーストオーバーレイが作成された後に表示します。
署名	`present() => Promise<void>`

CSSシャドウパーツ

名前	説明
`button`	トースト内に表示される任意のボタン要素。
`button cancel`	トースト内に表示される、役割が "cancel" の任意のボタン要素。
`container`	すべての子要素をラップする要素。
`header`	トーストのヘッダーテキスト。
`icon`	トーストコンテンツの横に表示されるアイコン。
`message`	トーストの本文テキスト。

CSSカスタムプロパティ

名前	説明
`--background`	トーストの背景
`--border-color`	トーストのボーダー色
`--border-radius`	トーストのボーダー半径
`--border-style`	トーストのボーダースタイル
`--border-width`	トーストのボーダー幅
`--box-shadow`	トーストのボックスシャドウ
`--button-color`	ボタンテキストの色
`--color`	トーストテキストの色
`--end`	方向が左から右の場合、右からの位置。右から左の場合、左からの位置。
`--height`	トーストの高さ
`--max-height`	トーストの最大高さ
`--max-width`	トーストの最大幅
`--min-height`	トーストの最小高さ
`--min-width`	トーストの最小幅
`--start`	方向が左から右の場合、左からの位置。右から左の場合、右からの位置。
`--white-space`	トーストメッセージのホワイトスペース
`--width`	トーストの幅

名前	説明
`--background`	トーストの背景
`--border-color`	トーストのボーダー色
`--border-radius`	トーストのボーダー半径
`--border-style`	トーストのボーダースタイル
`--border-width`	トーストのボーダー幅
`--box-shadow`	トーストのボックスシャドウ
`--button-color`	ボタンテキストの色
`--color`	トーストテキストの色
`--end`	方向が左から右の場合、右からの位置。右から左の場合、左からの位置。
`--height`	トーストの高さ
`--max-height`	トーストの最大高さ
`--max-width`	トーストの最大幅
`--min-height`	トーストの最小高さ
`--min-width`	トーストの最小幅
`--start`	方向が左から右の場合、左からの位置。右から左の場合、右からの位置。
`--white-space`	トーストメッセージのホワイトスペース
`--width`	トーストの幅

スロット

このコンポーネントで利用可能なスロットはありません。

インライントースト（推奨）​

isOpen の使用​

コントローラートースト​

破棄​

配置​

相対配置​

スワイプで破棄​

レイアウト​

アイコン​

テーマ​

アクセシビリティ​

フォーカスの管理​

スクリーンリーダー​

役割​

トーストボタンの説明​

ヒント​

インターフェース​

ToastButton​

ToastOptions​

プロパティ​

animated​

buttons​

color​

cssClass​

duration​

enterAnimation​

header​

htmlAttributes​

icon​

isOpen​

keyboardClose​

layout​

leaveAnimation​

message​

mode​

position​

positionAnchor​

swipeGesture​

translucent​

trigger​

イベント​

メソッド​

dismiss​

onDidDismiss​

onWillDismiss​

present​

CSSシャドウパーツ​

CSSカスタムプロパティ​

スロット​

目次