ion-toast

shadow

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

Inline Toasts (Recommended)

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

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

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

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.

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

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

Theming

Interfaces

ToastButton

interface ToastButton {
  text?: string;
  icon?: string;
  side?: 'start' | 'end';
  role?: 'cancel' | string;
  cssClass?: string | string[];
  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;
}

アクセシビリティ

フォーカスの管理

トーストはさりげなく通知するものであり、ユーザーの邪魔をするものではありません。トーストを消すためにユーザーの操作が必要であってはなりません。そのため、トーストが表示されても、フォーカスが自動的に移動することはありません。

スクリーンリーダー

ion-toast は、デフォルトで aria-live="polite" と aria-atomic="true" が設定されています。

aria-live を指定すると、トーストの内容が更新されたときにスクリーンリーダがアナウンスするようになります。しかし、この属性は 'polite' に設定されているため、スクリーン・リーダーは通常、現在のタスクを中断することはありません。開発者は htmlAttributes プロパティを使用して aria-live を 'assertive' に設定することで、この動作をカスタマイズすることができます。これにより、トーストが更新されると、スクリーン・リーダーはすぐにユーザーに通知し、それまでの更新を中断させる可能性があります。

また、aria-atomic="true"を設定すると、トースト全体を1つのユニットとしてアナウンスすることができます。これはトーストのコンテンツを動的に更新するときに便利で、スクリーン・リーダーが変更されたコンテンツのみをアナウンスすることを防ぎます。

ヒント

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

• トーストの解除にユーザーの操作を必要としないようにします。例えば、トーストに "Dismiss" ボタンがあるのは良いですが、タイムアウト後にトーストが自動的に終了するようにします。通知のためにユーザーの操作が必要な場合は、代わりに ion-alert を使用することを検討してください。

• 複数のトーストを連続して開くことは避けてください。もし aria-live が 'assertive' に設定されている場合、スクリーンリーダーは新しいトーストをアナウンスするために現在のタスクの読み込みを中断し、前のトーストのコンテキストが失われる可能性があります。

• 長いメッセージのトーストの場合は、durationプロパティを調整して、ユーザーがトーストの内容を読むのに十分な時間を確保することを検討してください。

Properties

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 & Record<never, never> ｜ 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

header

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.
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 position of the toast on the screen.
Attribute	position
Type	"bottom" ｜ "middle" ｜ "top"
Default	'bottom'

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
didDismiss	Emitted after the toast has dismissed. Shorthand for ionToastDidDismiss.
didPresent	Emitted after the toast has presented. Shorthand for ionToastWillDismiss.
ionToastDidDismiss	Emitted after the toast has dismissed.
ionToastDidPresent	Emitted after the toast has presented.
ionToastWillDismiss	Emitted before the toast has dismissed.
ionToastWillPresent	Emitted before the toast has presented.
willDismiss	Emitted before the toast has dismissed. Shorthand for ionToastWillDismiss.
willPresent	Emitted before the toast has presented. Shorthand for ionToastWillPresent.

メソッド

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