バージョン: v8 (beta)

ion-toast

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

インライン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プロパティは無視されます。

Swipe to Dismiss

swipeGestureプロパティを使用することで、トーストをスワイプして消すことができます。この機能は位置を認識します。つまり、ユーザがスワイプする方向は position プロパティの値に基づいて変化します。さらに、ユーザーがスワイプする距離は 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
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',
      },
    },
  ],
});

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.
If adding buttons to a toast, always provide alternative ways of completing the actions associated with each button. This ensures that even if the toast dismisses before a user can read it, they can still complete the actions shown in the toast.
Avoid showing a toast with buttons from inside another overlay such as a modal. Modals and other overlays implement focus trapping that will prevent screen readers from moving focus to the toast to complete the actions. This may be confusing for users since the toast will still be announced by screen readers. This is true even if alternative ways of completing the actions associated with each button are implemented. Consider creating a live region within the focus-trapped modal instead of using a 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	If `true`, the toast will animate.
Attribute	`animated`
Type	`boolean`
Default	`true`

buttons

Description	An array of buttons for the toast.
Attribute	`undefined`
Type	`(string ｜ ToastButton)[] ｜ undefined`
Default	`undefined`

color

Description	The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see theming.
Attribute	`color`
Type	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined`
Default	`undefined`

cssClass

Description	Additional classes to apply for custom CSS. If multiple classes are provided they should be separated by spaces.
Attribute	`css-class`
Type	`string ｜ string[] ｜ undefined`
Default	`undefined`

duration

Description	How many milliseconds to wait before hiding the toast. By default, it will show until `dismiss()` is called.
Attribute	`duration`
Type	`number`
Default	`config.getNumber('toastDuration', 0)`

enterAnimation

Description	Animation to use when the toast is presented.
Attribute	`undefined`
Type	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
Default	`undefined`

Description	Header to be shown in the toast.
Attribute	`header`
Type	`string ｜ undefined`
Default	`undefined`

htmlAttributes

Description	Additional attributes to pass to the toast.
Attribute	`undefined`
Type	`undefined ｜ { [key: string]: any; }`
Default	`undefined`

icon

Description	The name of the icon to display, or the path to a valid SVG file. See `ion-icon`. https://ionic.io/ionicons
Attribute	`icon`
Type	`string ｜ undefined`
Default	`undefined`

isOpen

Description	If `true`, the toast will open. If `false`, the toast will close. Use this if you need finer grained control over presentation, otherwise just use the toastController or the `trigger` property. Note: `isOpen` will not automatically be set back to `false` when the toast dismisses. You will need to do that in your code.
Attribute	`is-open`
Type	`boolean`
Default	`false`

keyboardClose

Description	If `true`, the keyboard will be automatically dismissed when the overlay is presented.
Attribute	`keyboard-close`
Type	`boolean`
Default	`false`

layout

Description	Defines how the message and buttons are laid out in the toast. 'baseline': The message and the buttons will appear on the same line. Message text may wrap within the message container. 'stacked': The buttons containers and message will stack on top of each other. Use this if you have long text in your buttons.
Attribute	`layout`
Type	`"baseline" ｜ "stacked"`
Default	`'baseline'`

leaveAnimation

Description	Animation to use when the toast is dismissed.
Attribute	`undefined`
Type	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
Default	`undefined`

message

Description	Message to be shown in the toast. This property accepts custom HTML as a string. Content is parsed as plaintext by default. `innerHTMLTemplatesEnabled` must be set to `true` in the Ionic config before custom HTML can be used.
Attribute	`message`
Type	`IonicSafeString ｜ string ｜ undefined`
Default	`undefined`

mode

Description	The mode determines which platform styles to use.
Attribute	`mode`
Type	`"ios" ｜ "md"`
Default	`undefined`

position

Description	The starting position of the toast on the screen. Can be tweaked further using the `positionAnchor` property.
Attribute	`position`
Type	`"bottom" ｜ "middle" ｜ "top"`
Default	`'bottom'`

positionAnchor

Description	The element to anchor the toast's position to. Can be set as a direct reference or the ID of the element. With `position="bottom"`, the toast will sit above the chosen element. With `position="top"`, the toast will sit below the chosen element. With `position="middle"`, the value of `positionAnchor` is ignored.
Attribute	`position-anchor`
Type	`HTMLElement ｜ string ｜ undefined`
Default	`undefined`

swipeGesture

Description	If set to 'vertical', the Toast can be dismissed with a swipe gesture. The swipe direction is determined by the value of the `position` property: `top`: The Toast can be swiped up to dismiss. `bottom`: The Toast can be swiped down to dismiss. `middle`: The Toast can be swiped up or down to dismiss.
Attribute	`swipe-gesture`
Type	`"vertical" ｜ undefined`
Default	`undefined`

translucent

Description	If `true`, the toast will be translucent. Only applies when the mode is `"ios"` and the device supports `backdrop-filter`.
Attribute	`translucent`
Type	`boolean`
Default	`false`

trigger

Description	An ID corresponding to the trigger element that causes the toast to open when clicked.
Attribute	`trigger`
Type	`string ｜ undefined`
Default	`undefined`

イベント

Name	Description	Bubbles
`didDismiss`	Emitted after the toast has dismissed. Shorthand for ionToastDidDismiss.	`true`
`didPresent`	Emitted after the toast has presented. Shorthand for ionToastWillDismiss.	`true`
`ionToastDidDismiss`	Emitted after the toast has dismissed.	`true`
`ionToastDidPresent`	Emitted after the toast has presented.	`true`
`ionToastWillDismiss`	Emitted before the toast has dismissed.	`true`
`ionToastWillPresent`	Emitted before the toast has presented.	`true`
`willDismiss`	Emitted before the toast has dismissed. Shorthand for ionToastWillDismiss.	`true`
`willPresent`	Emitted before the toast has presented. Shorthand for ionToastWillPresent.	`true`

メソッド

dismiss

Description	Dismiss the toast overlay after it has been presented.
Signature	`dismiss(data?: any, role?: string) => Promise<boolean>`

onDidDismiss

Description	Returns a promise that resolves when the toast did dismiss.
Signature	`onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

onWillDismiss

Description	Returns a promise that resolves when the toast will dismiss.
Signature	`onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

present

Description	Present the toast overlay after it has been created.
Signature	`present() => Promise<void>`

CSS Shadow Parts

Name	Description
`button`	Any button element that is displayed inside of the toast.
`button cancel`	Any button element with role "cancel" that is displayed inside of the toast.
`container`	The element that wraps all child elements.
`header`	The header text of the toast.
`icon`	The icon that appears next to the toast content.
`message`	The body text of the toast.

CSSカスタムプロパティ

Name	Description
`--background`	Background of the toast
`--border-color`	Border color of the toast
`--border-radius`	Border radius of the toast
`--border-style`	Border style of the toast
`--border-width`	Border width of the toast
`--box-shadow`	Box shadow of the toast
`--button-color`	Color of the button text
`--color`	Color of the toast text
`--end`	Position from the right if direction is left-to-right, and from the left if direction is right-to-left
`--height`	Height of the toast
`--max-height`	Maximum height of the toast
`--max-width`	Maximum width of the toast
`--min-height`	Minimum height of the toast
`--min-width`	Minimum width of the toast
`--start`	Position from the left if direction is left-to-right, and from the right if direction is right-to-left
`--white-space`	White space of the toast message
`--width`	Width of the toast

Slots

No slots available for this component.

インラインToasts (推奨)​

Using isOpen​​

Controller Toasts​

Dismissing​

ポジショニング​

相対的な位置​

Swipe to Dismiss​

レイアウト​

Icons​

テーマ​

アクセシビリティ​

フォーカスの管理​

スクリーンリーダー​

役割​

トーストボタンの説明​

Tips​

Interfaces​

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 Shadow Parts​

CSSカスタムプロパティ​

Slots​

Contents