ion-toast

shadow

Toast 是现代应用中常用的微妙通知。它可用于提供有关操作的反馈或显示系统消息。Toast 出现在应用内容的顶部，应用可以将其关闭以恢复用户与应用的交互。

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

内联吐司（推荐）

¥Inline Toasts (Recommended)

可以通过直接在模板中编写组件来使用 ion-toast。这减少了展示吐司所需连接的处理程序的数量。

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

使用 isOpen​

¥Using isOpen​

ion-toast 上的 isOpen 属性允许开发者从其应用状态控制 toast 的渲染状态。这意味着当 isOpen 设置为 true 时，将显示 Toast；当 isOpen 设置为 false 时，将取消 Toast。

¥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 使用单向数据绑定，这意味着当 toast 关闭时它不会自动设置为 false。开发者应该监听 ionToastDidDismiss 或 didDismiss 事件并将 isOpen 设置为 false。这样做的原因是它阻止了 ion-toast 的内部与应用的状态紧密耦合。通过单向数据绑定，Toast 只需要关心反应变量提供的布尔值。通过双向数据绑定，Toast 需要关注布尔值以及反应变量本身的存在。这可能会导致不确定的行为并使应用更难以调试。

¥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

Toast 旨在作为微妙的通知，不应打扰用户。因此，不需要用户交互来消除 toast。

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

通过传递在 toast 选项的 duration 中显示的毫秒数，可以在特定时间后自动关闭 toast。如果添加了角色为 "cancel" 的按钮，则该按钮将关闭 toast。要在创建后关闭 toast，请在实例上调用 dismiss() 方法。

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

按硬件后退按钮不会消除 toast，因为它们不应该打扰用户。

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

下面的示例演示如何使用 buttons 属性添加一个单击时自动关闭 toast 的按钮，以及如何收集关闭事件的 role。

¥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

Toast 可以放置在视口的顶部、底部或中间。该职位可以在创建时传递。可能的值为 top、bottom 和 middle。如果未指定位置，则 toast 将显示在视口的底部。

¥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

如果 Toast 与导航元素（例如页眉、页脚或 FAB）一起显示，则默认情况下 Toast 可能会与这些元素重叠。可以使用 positionAnchor 属性来修复此问题，该属性采用元素引用或 ID。Toast 将相对于所选元素定位，使用 position="top" 时显示在其下方，使用 position="bottom" 时显示在其上方。使用 position="middle" 时，忽略 positionAnchor 属性。

¥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

可以使用 swipeGesture 属性滑动 Toast 来关闭。此功能具有位置感知功能，这意味着用户需要滑动的方向将根据 position 属性的值而改变。此外，用户需要滑动的距离可能会受到 positionAnchor 属性的影响。

¥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

Toast 中的按钮容器可以与消息显示在同一行，也可以使用 layout 属性堆叠在单独的行上。堆叠布局应与具有长文本值的按钮一起使用。此外，堆叠 Toast 布局中的按钮可以使用 start 或 end 的 side 值，但不能同时使用两者。

¥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

可以在 toast 内的内容旁边添加一个图标。一般来说，toast 中的图标应该用于添加额外的样式或上下文，而不是为了吸引用户的注意力或提高 toast 的优先级。如果你希望向用户传达更高优先级的消息或保证得到响应，我们建议使用 警报。

¥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

Toast 旨在提供微妙的通知，而不是打扰用户。不应需要用户交互来消除 toast。因此，当出现吐司时，焦点不会自动移动到吐司上。

¥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

Toast 设置 aria 属性，以便对屏幕阅读器来说是 accessible，但如果这些属性描述性不够，或者与应用中使用 Toast 的方式不一致，则可以覆盖这些属性。

¥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 在内部 .toast-content 元素上设置了 role="status" 和 aria-live="polite"。这会导致屏幕阅读器仅读出 toast 消息和标题。当吐司出现时，按钮和图标不会被宣布。

¥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 使屏幕阅读器在更新时宣布 toast 的内容。但是，由于该属性设置为 'polite'，屏幕阅读器不应中断当前任务。

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

由于 toast 旨在作为微妙的通知，因此 aria-live 绝对不应该设置为 "assertive"。如果开发者需要用重要消息打断用户，我们建议使用 alert。

¥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 按钮说明

¥Toast Buttons Description

与包含文本的按钮交互时，屏幕阅读器将读取它们。如果按钮仅包含图标，或者需要除现有文本之外的描述，则应通过将 aria-label 传递到按钮上的 htmlAttributes 属性来为按钮分配标签。

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

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

虽然这不是完整列表，但以下是使用 Toast 时需要遵循的一些准则。

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

• 不需要用户交互来消除 toast。例如，在 Toast 中有一个 "退出" 按钮就可以，但 Toast 也应该在超时后自动关闭。如果你需要通知的用户交互，请考虑使用 alert。

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

• 对于包含长消息的 Toast，请考虑调整 duration 属性，以便用户有足够的时间阅读 Toast 的内容。

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

• 如果向 Toast 添加按钮，请始终提供完成与每个按钮关联的操作的替代方法。这确保了即使 Toast 在用户可以阅读之前消失，他们仍然可以完成 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.

• 避免显示带有来自另一个覆盖层（例如 modal）内的按钮的 Toast。模态框和其他覆盖层实现了 焦点捕捉，它将阻止屏幕阅读器将焦点移至 toast 来完成操作。这可能会让用户感到困惑，因为屏幕阅读器仍会宣布 toast。即使实现了完成与每个按钮关联的操作的替代方法，情况也是如此。考虑在焦点捕获模态中创建 居住区，而不是使用 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;
}

属性

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

事件

¥Events

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

方法

¥Methods

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 阴影部分

¥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 自定义属性

¥CSS Custom Properties

iOS

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

MD

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.