ion-toast

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 可以通过在模板中直接编写组件来使用。这减少了你需要连接的处理程序数量，从而渲染 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 使用单向数据绑定，这意味着在通知被关闭时，它不会自动设置为 false。开发者应监听 ionToastDidDismiss 或 didDismiss 事件，并将 isOpen 设置为 false。这样做的原因是，它可以防止 ion-toast 的内部逻辑与应用状态紧密耦合。使用单向数据绑定时，通知只需要关心响应式变量提供的布尔值。而使用双向数据绑定时，通知不仅需要关心布尔值，还需要关心响应式变量本身的存在。这可能导致非确定性行为，使应用更难调试。

控制器吐司

🌐 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

吐司可以放置在视口的顶部、底部或中间。位置可以在创建时传入。可能的值是 top、bottom 和 middle。如果未指定位置，吐司将显示在视口的底部。

🌐 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

如果在导航元素（例如页眉、页脚或 FAB）旁显示 toast，则默认情况下 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 布局中的按钮可以使用 side 值为 start 或 end，但不能同时使用两者。

🌐 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 的优先级。如果你希望向用户传达更高优先级的信息或保证得到回应，我们建议使用 Alert 代替。

🌐 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。因此，当 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

吐司会设置 aria 属性，以便让屏幕阅读器可以访问，但如果这些属性描述不够，或与吐司在应用中的使用方式不一致，它们可能会被覆盖。

🌐 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 消息和标题。当 toast 出现时，按钮和图标将不会被朗读。

aria-live 会在吐司更新时让屏幕阅读器朗读其内容。但是，由于该属性被设置为 'polite'，屏幕阅读器不应打断当前任务。

由于 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
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

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

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

不要求用户交互即可关闭提示。例如，在提示中有一个“关闭”按钮是可以的，但提示也应在超时后自动关闭。如果通知需要用户交互，请考虑改用警报。
对于带有较长信息的 toast，考虑调整 duration 属性，以便用户有足够的时间阅读 toast 的内容。
如果在吐司通知中添加按钮，请始终提供完成与每个按钮相关操作的替代方法。这确保即使吐司在用户阅读之前就消失，他们仍然可以完成吐司中显示的操作。
避免在其他覆盖层（如模态框）内部显示带按钮的 toast。模态框和其他覆盖层会实现焦点陷阱，这会阻止屏幕阅读器将焦点移到 toast 以完成操作。这可能会让用户感到困惑，因为屏幕阅读器仍会朗读 toast。即使为每个按钮关联的操作实现了替代完成方式，情况也同样如此。可以考虑在焦点受限的模态框内创建一个实时区域，而不是使用 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

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. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render.
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. 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.
Signature	`dismiss(data?: any, role?: string) => Promise<boolean>`
Parameters	data: 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	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`	Groups the icon, content, and buttons.
`content`	The live region that contains the header and message.
`header`	The header text of the toast.
`icon`	The icon that appears next to the toast content.
`message`	The body text of the toast.
`wrapper`	The outer wrapper for the toast overlay.

CSS 自定义属性

🌐 CSS Custom Properties

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

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.

内联吐司（推荐）​

使用 isOpen​​

控制器吐司​

退出​

定位​

相对定位​

滑动即可关闭​

布局​

图标​

主题化​

无障碍​

焦点管理​

屏幕阅读器​

角色​

Toast 按钮说明​

提示​

接口​

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

CSS 自定义属性​

插槽​

目录