ion-toast

shadow

トーストは、最近のアプリケーションでよく使われる小さな通知です。操作に関するフィードバックを提供したり、システムメッセージを表示したりするために使用されます。トーストは、アプリケーションのコンテンツの上に表示され、アプリケーションによって解除されると、アプリケーションとの対話を再開することができます。

インラインToasts (推奨)

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

Using isOpen​

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

isOpen は一方通行のデータバインディングを使用しているため、トーストが破棄されたときに自動的に false に設定されることはありません。開発者は ionToastDidDismiss または didDismiss イベントをリスニングして isOpen を false に設定する必要があります。この理由は、ion-toast の内部がアプリケーションの状態と密接に結合するのを防ぐためである。一方通行のデータバインディングでは、トーストはリアクティブ変数が提供するブーリアン値だけを気にすればよい。一方通行のデータバインディングでは、トーストはブーリアン値とリアクティブ変数の存在の両方に関心を持つ必要があります。これは、非決定的な動作につながり、アプリケーションのデバッグを困難にします。

Controller Toasts

Dismissing

トーストは静かな通知であり、ユーザーの邪魔をしないように意図されています。そのため、トーストを解除するためにユーザーの操作を必要とするべきではありません。

トーストは、トーストオプションの duration に表示するミリ秒数を渡すことで、特定の時間経過後に自動的に解除されるようにすることができます。もし "cancel" という役割を持つボタンが追加された場合、そのボタンがトーストを終了させます。作成後にトーストを破棄するには、インスタンスの dismiss() メソッドを呼び出してください。

ハードウェアの戻るボタンを押しても、トーストはユーザーの邪魔をしないようになっているので、トーストは破棄されません。

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

Console

Console messages will appear here when logged from the example above.

ポジショニング

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

相対的な位置

トーストがヘッダー、フッター、FABのようなナビゲーション要素と一緒に表示される場合、デフォルトではトーストはこれらの要素と重なるかもしれません。これは positionAnchor プロパティを使って修正することができます。position="top"を使用するとトーストは選択した要素に対して相対的な位置になり、position="bottom"を使用するとその下に、position="bottom"を使用するとその上に表示されます。position="middle"を使用する場合、positionAnchorプロパティは無視されます。

レイアウト

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

Icons

トースト内のコンテンツの横にアイコンを追加することができます。一般的に、トーストのアイコンはスタイルやコンテキストを追加するために使用されるべきで、ユーザーの注意を引いたり、トーストの優先順位を上げたりするために使用すべきではありません。より優先順位の高いメッセージをユーザーに伝えたい場合や、応答を保証したい場合は、代わりに Alert を使用することをお勧めします。

テーマ

アクセシビリティ

フォーカスの管理

トーストはさりげない通知であり、ユーザーを中断させるものではありません。トーストを解除するためにユーザが操作する必要はありません。そのため、トーストが表示されたときにフォーカスが自動的にトーストに移動することはありません。

スクリーンリーダー

トーストは、スクリーンリーダーからaccessibleであるためにariaプロパティを設定しますが、これらのプロパティは、十分な説明がない場合や、トーストがアプリでどのように使用されているかに合っていない場合は、上書きすることができます。

役割

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

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

トーストはさりげなく通知することを意図しているので、aria-liveを"assertive"に設定すべきではありません。開発者が重要なメッセージでユーザーを中断させる必要がある場合は、alertを使用することをお勧めします。

トーストボタンの説明

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

Angular

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

Javascript

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

React

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

Vue

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

Tips

While this is not a complete list, here are some guidelines to follow when using toasts.

• Do not require user interaction to dismiss toasts. For example, having a "Dismiss" button in the toast is fine, but the toast should also automatically dismiss on its own after a timeout period. If you need user interaction for a notification, consider using an alert instead.

• For toasts with long messages, consider adjusting the duration property to allow users enough time to read the content of the toast.

Interfaces

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

Description	trueの場合、トーストはアニメーションします。
Attribute	animated
Type	boolean
Default	true

buttons

Description	トースト用のボタンがずらり。
Attribute	undefined
Type	(string ｜ ToastButton)[] ｜ undefined
Default	undefined

color

Description	アプリケーションのカラーパレットから使用する色を指定します。デフォルトのオプションは以下の通りです。 "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", と "dark" です．色に関する詳しい情報は theming を参照してください。
Attribute	color
Type	"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
Default	undefined

cssClass

Description	カスタムCSSに適用する追加のクラス。複数のクラスを指定する場合は、スペースで区切る必要があります。
Attribute	css-class
Type	string ｜ string[] ｜ undefined
Default	undefined

duration

Description	トーストを隠すまでに何ミリ秒待つかを指定します。デフォルトでは、dismiss()が呼ばれるまで表示されます。
Attribute	duration
Type	number
Default	config.getNumber('toastDuration', 0)

enterAnimation

Description	乾杯の音頭をとるときに使うアニメーションです。
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

header

Description	トーストに表示されるヘッダー。
Attribute	header
Type	string ｜ undefined
Default	undefined

htmlAttributes

Description	トーストに渡す追加の属性。
Attribute	undefined
Type	undefined ｜ { [key: string]: any; }
Default	undefined

icon

Description	表示するアイコンの名前、または有効なSVGファイルへのパスを指定します。ion-icon`を参照。https://ionic.io/ionicons
Attribute	icon
Type	string ｜ undefined
Default	undefined

isOpen

Description	もし true ならば、トーストは表示されます。もし false ならば、トーストは閉じます。プレゼンテーションの細かい制御が必要な場合はこれを使用し、そうでない場合は toastController または trigger プロパティを使用してください。注意: トーストが終了しても isOpen は自動的に false に戻りません。あなたのコードでそれを行う必要があります。
Attribute	is-open
Type	boolean
Default	false

keyboardClose

Description	trueの場合、オーバーレイが表示されたときにキーボードが自動的に解除されます。
Attribute	keyboard-close
Type	boolean
Default	false

layout

Description	トーストのメッセージやボタンの配置を定義します。'baseline'を指定します。メッセージとボタンは同じ行に表示されます。メッセージテキストはメッセージコンテナ内で折り返すことができます。'stacked':ボタンコンテナとメッセージが重なるように表示されます。ボタンに長いテキストがある場合に使用します。
Attribute	layout
Type	"baseline" ｜ "stacked"
Default	'baseline'

leaveAnimation

Description	トーストの解散時に使用するアニメーションです。
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

message

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

mode

Description	modeは、どのプラットフォームのスタイルを使用するかを決定します。
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

position

Description	画面上のトーストの開始位置。 positionAnchorプロパティを使ってさらに微調整できます。
Attribute	position
Type	"bottom" ｜ "middle" ｜ "top"
Default	'bottom'

positionAnchor

Description	トーストの位置を固定する要素。直接参照するか、要素のIDを指定します。position="bottom"の場合、トーストは選択した要素の上に表示されます。position="top"の場合、トーストは選択した要素の下に位置します。position="middle"の場合、positionAnchor`の値は無視される。
Attribute	position-anchor
Type	HTMLElement ｜ string ｜ undefined
Default	undefined

translucent

Description	trueの場合、トーストは半透明になります。modeが "ios" で、デバイスが backdrop-filter をサポートしている場合にのみ適用されます。
Attribute	translucent
Type	boolean
Default	false

trigger

Description	クリックされたときにトーストを開かせるトリガー要素に対応するID。
Attribute	trigger
Type	string ｜ undefined
Default	undefined

イベント

Name	Description
didDismiss	トーストが終了した後に発行されます。ionToastDidDismissの略記。
didPresent	トーストがはじまった後に発行されます。ionToastWillDismissの略語。
ionToastDidDismiss	トーストが解散した後に発行されます。
ionToastDidPresent	トーストが提示された後に発行されます。
ionToastWillDismiss	乾杯が解散する前に発行されます。
ionToastWillPresent	トーストが提示される前に発行されます。
willDismiss	トーストが終了する前に発行されます。ionToastWillDismissの略語です。
willPresent	トーストが表示される前に発行されます。ionToastWillPresentの略記。

メソッド

dismiss

Description	トーストのオーバーレイが提示された後、それを解除します。
Signature	dismiss(data?: any, role?: string) => Promise<boolean>

onDidDismiss

Description	トーストが解散したことを解決するPromiseを返します。
Signature	onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss

Description	トーストが解散するタイミングを解決するPromiseを返します。
Signature	onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

present

Description	トーストのオーバーレイを作成した後に提示します。
Signature	present() => Promise<void>

CSS Shadow Parts

Name	Description
button	トーストの内側に表示される任意のボタン要素。
button cancel	トーストの内側に表示される、"cancel "というロールを持つボタン要素。
container	すべての子要素を包む要素。
header	乾杯のヘッダーテキストです。
icon	トーストの内容の横に表示されるアイコンです。
message	乾杯の音頭の本文です。

CSSカスタムプロパティ

Name	Description
--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	トーストの幅

Slots

No slots available for this component.