版本：v8

ion-toast

Toast 是一种现代应用中常用的微妙通知。它可以用于提供操作反馈或显示系统消息。toast 显示在应用内容的上方，可以通过应用关闭来恢复用户与应用的交互。

内联 Toast（推荐）

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

使用 `isOpen`

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

isOpen 使用单向数据绑定，意味着当 toast 关闭时它不会自动被设置为 false。开发者应监听 ionToastDidDismiss 或 didDismiss 事件，并将 isOpen 设置为 false。这样做的原因是防止 ion-toast 的内部实现与应用状态紧密耦合。通过单向数据绑定，toast 只需关心反应式变量提供的布尔值。而使用双向数据绑定时，toast 需要同时关心布尔值和反应式变量本身的存在性。这可能导致非确定性行为并使应用更难调试。

控制器 Toast

关闭

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

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

按下硬件返回按钮不会关闭 toast，因为它们不应该打扰用户。

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

控制台

控制台消息将在上方示例中调用 console.log 时显示在此处。

定位

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

相对定位

如果 toast 与导航元素（如页眉、页脚或 FAB）一起显示，toast 可能会默认覆盖这些元素。这可以通过 positionAnchor 属性来解决，该属性接受元素引用或 ID。toast 将相对于所选元素定位，当使用 position="top" 时显示在元素下方，当使用 position="bottom" 时显示在元素上方。当使用 position="middle" 时，positionAnchor 属性将被忽略。

滑动关闭

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

布局

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

图标

可以在 toast 内部的内容旁边添加图标。通常，toast 中的图标应用于增加额外的样式或上下文，而不是吸引用户的注意力或提升 toast 的优先级。如果您想向用户传达更重要的消息或确保获得响应，我们建议使用提示框代替。

主题

无障碍

焦点管理

Toast 旨在作为微妙的通知，不打算打扰用户。关闭 toast 不应需要用户交互。因此，当 toast 显示时，焦点不会自动移动到 toast 上。

屏幕阅读器

Toast 设置了 aria 属性以便屏幕阅读器可以访问，但如果这些属性不够描述性或与 toast 在应用中的使用方式不符，可以覆盖它们。

角色

ion-toast 在内部的 .toast-content 元素上设置了 role="status" 和 aria-live="polite"。这使屏幕阅读器只播报 toast 消息和标题。按钮和图标在 toast 显示时不会被播报。

aria-live 使屏幕阅读器在 toast 内容更新时播报其内容。但是，由于该属性设置为 'polite'，屏幕阅读器不应中断当前任务。

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

Toast 按钮描述

包含文本的按钮在与之交互时将由屏幕阅读器朗读。如果按钮仅包含图标，或需要与现有文本不同的描述，则应通过向按钮的 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',
      },
    },
  ],
});

提示

虽然这不是一个完整的列表，但以下是一些使用 toast 时的指导原则。

关闭 toast 时不要要求用户交互。例如，在 toast 中放置"关闭"按钮是可以的，但 toast 也应在超时后自动关闭。如果您需要在通知中获取用户交互，请考虑使用提示框代替。
对于消息较长的 toast，请考虑调整 duration 属性，以便用户有足够时间阅读 toast 的内容。
如果在 toast 中添加按钮，请始终为每个按钮关联的操作提供替代完成方式。这确保了即使用户在阅读之前 toast 已关闭，他们仍然可以完成 toast 中显示的操作。
避免从其他叠加层（如模态框）内部显示带有按钮的 toast。模态框和其他叠加层实现了焦点陷阱，这将阻止屏幕阅读器将焦点移动到 toast 上来完成操作。这可能会使用户感到困惑，因为屏幕阅读器仍然会播报 toast。即使实现了每个按钮关联操作的替代方式，情况也是如此。请考虑在焦点陷阱模态框内创建一个活动区域，而不是使用 toast。

接口

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;
}

属性

animated

说明	If `true`, the toast will animate.
属性	`animated`
类型	`boolean`
默认值	`true`

buttons

说明	An array of buttons for the toast.
属性	`undefined`
类型	`(string ｜ ToastButton)[] ｜ undefined`
默认值	`undefined`

color

说明	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.
属性	`color`
类型	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined`
默认值	`undefined`

cssClass

说明	Additional classes to apply for custom CSS. If multiple classes are provided they should be separated by spaces.
属性	`css-class`
类型	`string ｜ string[] ｜ undefined`
默认值	`undefined`

duration

说明	How many milliseconds to wait before hiding the toast. By default, it will show until `dismiss()` is called.
属性	`duration`
类型	`number`
默认值	`config.getNumber('toastDuration', 0)`

enterAnimation

说明	Animation to use when the toast is presented.
属性	`undefined`
类型	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
默认值	`undefined`

header

说明	Header to be shown in the toast.
属性	`header`
类型	`string ｜ undefined`
默认值	`undefined`

htmlAttributes

说明	Additional attributes to pass to the toast.
属性	`undefined`
类型	`undefined ｜ { [key: string]: any; }`
默认值	`undefined`

icon

说明	The name of the icon to display, or the path to a valid SVG file. See `ion-icon`. https://ionic.io/ionicons
属性	`icon`
类型	`string ｜ undefined`
默认值	`undefined`

isOpen

说明	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.
属性	`is-open`
类型	`boolean`
默认值	`false`

keyboardClose

说明	If `true`, the keyboard will be automatically dismissed when the overlay is presented.
属性	`keyboard-close`
类型	`boolean`
默认值	`false`

layout

说明	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.
属性	`layout`
类型	`"baseline" ｜ "stacked"`
默认值	`'baseline'`

leaveAnimation

说明	Animation to use when the toast is dismissed.
属性	`undefined`
类型	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
默认值	`undefined`

message

说明	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.
属性	`message`
类型	`IonicSafeString ｜ string ｜ undefined`
默认值	`undefined`

mode

说明	The mode determines which platform styles to use. 这是一个虚拟属性，在初始化时设置一次，之后更改其值不会更新组件。
属性	`mode`
类型	`"ios" ｜ "md"`
默认值	`undefined`

position

说明	The starting position of the toast on the screen. Can be tweaked further using the `positionAnchor` property.
属性	`position`
类型	`"bottom" ｜ "middle" ｜ "top"`
默认值	`'bottom'`

positionAnchor

说明	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.
属性	`position-anchor`
类型	`HTMLElement ｜ string ｜ undefined`
默认值	`undefined`

swipeGesture

说明	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.
属性	`swipe-gesture`
类型	`"vertical" ｜ undefined`
默认值	`undefined`

translucent

说明	If `true`, the toast will be translucent. Only applies when the mode is `"ios"` and the device supports `backdrop-filter`.
属性	`translucent`
类型	`boolean`
默认值	`false`

trigger

说明	An ID corresponding to the trigger element that causes the toast to open when clicked.
属性	`trigger`
类型	`string ｜ undefined`
默认值	`undefined`

事件

Name	说明	冒泡
`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

说明	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.
签名	`dismiss(data?: any, role?: string) => Promise<boolean>`
参数	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

说明	Returns a promise that resolves when the toast did dismiss.
签名	`onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

onWillDismiss

说明	Returns a promise that resolves when the toast will dismiss.
签名	`onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

present

说明	Present the toast overlay after it has been created.
签名	`present() => Promise<void>`

CSS Shadow Parts

Name	说明
`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 自定义属性

Name	说明
`--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	说明
`--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

插槽

该组件没有可用的插槽。

内联 Toast（推荐）​

使用 isOpen​

控制器 Toast​

关闭​

定位​

相对定位​

滑动关闭​

布局​

图标​

主题​

无障碍​

焦点管理​

屏幕阅读器​

角色​

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

CSS 自定义属性​

插槽​

目录