メインコンテンツまでスキップ
バージョン: v8

ion-toast

shadow

A Toast is a subtle notification commonly used in modern applications. It can be used to provide feedback about an operation or to display a system message. The toast appears on top of the app's content, and can be dismissed by the app to resume user interaction with the app.

ion-toast can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the toast.

Using isOpen​​

The isOpen property on ion-toast allows developers to control the presentation state of the toast from their application state. This means when isOpen is set to true the toast will be presented and when isOpen is set to false the toast will be dismissed.

isOpen uses a one-way data binding, meaning it will not automatically be set to false when the toast is dismissed. Developers should listen for the ionToastDidDismiss or didDismiss event and set isOpen to false. The reason for this is it prevents the internals of ion-toast from being tightly coupled with the state of the application. With a one way data binding, the toast only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the toast needs to concern itself with both the boolean value as well as the existence of the reactive variable itself. This can lead to non-deterministic behaviors and make applications harder to debug.

Controller Toasts​

Dismissing​

Toasts are intended to be subtle notifications and should not interrupt the user. As a result, user interaction should not be required to dismiss the toast.

The toast can be dismissed automatically after a specific amount of time by passing the number of milliseconds to display it in the duration of the toast options. If a button with a role of "cancel" is added, then that button will dismiss the toast. To dismiss the toast after creation, call the dismiss() method on the instance.

Pressing the hardware back button does not dismiss toasts since they are not supposed to interrupt the user.

The following example demonstrates how to use the buttons property to add a button that automatically dismisses the toast when clicked, as well as how to collect the role of the dismiss event.

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

Positioning​

Toasts can be positioned at the top, bottom or middle of the viewport. The position can be passed upon creation. The possible values are top, bottom and middle. If the position is not specified, the toast will be displayed at the bottom of the viewport.

Relative Positioning​

If a toast is presented alongside navigation elements such as a header, footer, or FAB, the toast may overlap these elements by default. This can be fixed using the positionAnchor property, which takes either an element reference or an ID. The toast will be positioned relative to the chosen element, appearing below it when using position="top" or above it when using position="bottom". When using position="middle", the positionAnchor property is ignored.

Swipe to Dismiss​

Toasts can be swiped to dismiss by using the swipeGesture property. This feature is position-aware, meaning the direction that users need to swipe will change based on the value of the position property. Additionally, the distance users need to swipe may be impacted by the positionAnchor property.

Layout​

Button containers within the toast can be displayed either on the same line as the message or stacked on separate lines using the layout property. The stacked layout should be used with buttons that have long text values. Additionally, buttons in a stacked toast layout can use a side value of either start or end, but not both.

Icons​

An icon can be added next to the content inside of the toast. In general, icons in toasts should be used to add additional style or context, not to grab the user's attention or elevate the priority of the toast. If you wish to convey a higher priority message to the user or guarantee a response, we recommend using an Alert instead.

Theming​

Accessibility​

Focus Management​

Toasts are intended to be subtle notifications and are not intended to interrupt the user. User interaction should not be required to dismiss the toast. As a result, focus is not automatically moved to a toast when one is presented.

Screen Readers​

Toasts set aria properties in order to be accessible to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the toast is being used in an app.

Role​

ion-toast has role="status" and aria-live="polite" set on the inner .toast-content element. This causes screen readers to only announce the toast message and header. Buttons and icons will not be announced when the toast is presented.

aria-live causes screen readers to announce the content of the toast when it is updated. However, since the attribute is set to 'polite', screen readers should not interrupt the current task.

Since toasts are intended to be subtle notification, aria-live should never be set to "assertive". If developers need to interrupt the user with an important message, we recommend using an alert.

Toast Buttons Description​

Buttons containing text will be read by a screen reader when they are interacted with. If a button contains only an icon, or a description other than the existing text is desired, a label should be assigned to the button by passing aria-label to the htmlAttributes property on the button.

const toast = await this.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;
  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;
}

Properties​

animated​

Descriptiontrueの場合、トーストはアニメーションします。
Attributeanimated
Typeboolean
Defaulttrue

buttons​

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

color​

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

cssClass​

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

duration​

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

enterAnimation​

Description乾杯の音頭をとるときに使うアニメーションです。
Attributeenter-animation
Type((baseEl: any, opts?: any) => Animation) ｜ undefined
Defaultundefined
Descriptionトーストに表示されるヘッダー。
Attributeheader
Typestring ｜ undefined
Defaultundefined

htmlAttributes​

Descriptionトーストに渡す追加の属性。
Attributehtml-attributes
Typeundefined ｜ { [key: string]: any; }
Defaultundefined

icon​

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

isOpen​

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

keyboardClose​

Descriptiontrueの場合、オーバーレイが表示されたときにキーボードが自動的に解除されます。
Attributekeyboard-close
Typeboolean
Defaultfalse

layout​

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

leaveAnimation​

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

message​

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

mode​

Descriptionmodeは、どのプラットフォームのスタイルを使用するかを決定します。

This is a virtual property that is set once during initialization and will not update if you change its value after the initial render.
Attributemode
Type"ios" ｜ "md"
Defaultundefined

position​

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

positionAnchor​

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

swipeGesture​

Descriptionvertical'に設定すると、スワイプジェスチャーでToastを消すことができます。スワイプの方向は position プロパティの値によって決まります：top：top: 上方向にスワイプすることでトーストを消すことができます。top: トーストを上方向にスワイプして消すことができます：top: 上方向にスワイプするとToastが表示され、下方向にスワイプするとToastが表示されます。middle`：トーストは上下にスワイプして消すことができます。
Attributeswipe-gesture
Type"vertical" ｜ undefined
Defaultundefined

translucent​

Descriptiontrueの場合、トーストは半透明になります。modeが "ios" で、デバイスが backdrop-filter をサポートしている場合にのみ適用されます。
Attributetranslucent
Typeboolean
Defaultfalse

trigger​

Descriptionクリックされたときにトーストを開かせるトリガー要素に対応するID。
Attributetrigger
Typestring ｜ undefined
Defaultundefined

Events​

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

Methods​

dismiss​

DescriptionDismiss the toast overlay after it has been presented. This is a no-op if the overlay has not been presented yet. If you want to remove an overlay from the DOM that was never presented, use the remove method.
Signaturedismiss(data?: any, role?: string) => Promise<boolean>
Parametersdata: Any data to emit in the dismiss events.
role: The role of the element that is dismissing the toast. This can be useful in a button handler for determining which button was clicked to dismiss the toast. Some examples include: "cancel", "destructive", "selected", and "backdrop".

onDidDismiss​

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

onWillDismiss​

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

present​

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

CSS Shadow Parts​

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

CSS Custom Properties​

NameDescription
--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.

Contents

このページを編集