版本：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 的毫秒数传递到 Toast 选项的 duration 中，可以自动关闭 Toast。如果添加了一个角色为 "cancel" 的按钮，那么该按钮将关闭 Toast。要关闭创建后的 Toast，请调用实例上的 dismiss() 方法。

按下硬件后退按钮不会关闭 Toast，因为它们不应该打断用户。

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

控制台

控制台消息将出现在此处，当从上面的示例中记录时。

定位

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 布局中的按钮可以使用 side 值为 start 或 end，但不能同时使用两者。

图标

可以在 Toast 中的内容旁边添加一个图标。通常，Toast 中的图标应用于添加额外的样式或上下文，而不是吸引用户的注意力或提升 Toast 的优先级。如果您想向用户传达更高的优先级消息或保证响应，建议使用 Alert。

主题

无障碍性

焦点管理

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"。如果开发人员需要使用重要消息来打断用户，建议使用 alert。

Toast 按钮描述

包含文本的按钮将在交互时由屏幕阅读器读取。如果按钮只包含图标，或者需要其他描述而不是现有文本，则应通过将 aria-label 传递到按钮的 htmlAttributes 属性来为按钮分配标签。

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 也应该在一段时间后自动关闭。如果您需要用户交互才能进行通知，建议使用 alert。
对于包含较长消息的 Toast，请考虑调整 duration 属性，以便用户有足够的时间阅读 Toast 中的内容。
如果在 Toast 中添加按钮，请始终提供完成与每个按钮相关的操作的替代方法。这样可以确保即使 Toast 在用户能够阅读它之前消失，他们仍然可以完成 Toast 中显示的操作。
避免在另一个叠加层（如模态框）中显示带有按钮的 Toast。模态框和其他叠加层实现了焦点捕获，这将阻止屏幕阅读器将焦点移动到 Toast 以完成操作。这可能会让用户感到困惑，因为 Toast 仍然会由屏幕阅读器宣布。即使实现了完成与每个按钮相关的操作的替代方法，也是如此。考虑在焦点捕获的模态框内创建实时区域，而不是使用 Toast。

接口

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

属性

animated

描述	如果为 `true`，则 Toast 将进行动画。
属性	`animated`
类型	`boolean`
默认值	`true`

buttons

描述	Toast 的按钮数组。
属性	`undefined`
类型	`(string ｜ ToastButton)[] ｜ undefined`
默认值	`undefined`

color

描述	要从应用程序调色板中使用的颜色。默认选项为：`"primary"`、`"secondary"`、`"tertiary"`、`"success"`、`"warning"`、`"danger"`、`"light"`、`"medium"` 和 `"dark"`。有关颜色的更多信息，请参阅主题。
属性	`color`
类型	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined`
默认值	`undefined`

cssClass

描述	要应用于自定义 CSS 的附加类。如果提供多个类，则应使用空格分隔它们。
属性	`css-class`
类型	`string ｜ string[] ｜ undefined`
默认值	`undefined`

duration

描述	隐藏 Toast 之前等待的毫秒数。默认情况下，它将显示，直到调用 `dismiss()` 为止。
属性	`duration`
类型	`number`
默认值	`config.getNumber('toastDuration', 0)`

enterAnimation

描述	Toast 显示时要使用的动画。
属性	`undefined`
类型	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
默认值	`undefined`

描述	要在 Toast 中显示的标题。
属性	`header`
类型	`string ｜ undefined`
默认值	`undefined`

htmlAttributes

描述	要传递给 Toast 的附加属性。
属性	`undefined`
类型	`undefined ｜ { [key: string]: any; }`
默认值	`undefined`

icon

描述	要显示的图标名称，或有效 SVG 文件的路径。请参阅 `ion-icon`。 https://ionic.io/ionicons
属性	`icon`
类型	`string ｜ undefined`
默认值	`undefined`

isOpen

描述	如果为 `true`，则 Toast 将打开。如果为 `false`，则 Toast 将关闭。如果您需要对呈现进行更精细的控制，请使用此方法，否则只使用 toastController 或 `trigger` 属性。注意：当 Toast 消失时，`isOpen` 不会自动设置为 `false`。您需要在代码中进行设置。
属性	`is-open`
类型	`boolean`
默认值	`false`

keyboardClose

描述	如果为 `true`，则在呈现叠加层时键盘将自动消失。
属性	`keyboard-close`
类型	`boolean`
默认值	`false`

layout

描述	定义消息和按钮在 Toast 中的布局方式。'baseline'：消息和按钮将出现在同一行上。消息文本可能会在消息容器内换行。'stacked'：按钮容器和消息将彼此叠加。如果按钮中包含较长的文本，请使用此方法。
属性	`layout`
类型	`"baseline" ｜ "stacked"`
默认值	`'baseline'`

leaveAnimation

描述	Toast 消失时要使用的动画。
属性	`undefined`
类型	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
默认值	`undefined`

message

描述	要在 Toast 中显示的消息。此属性接受自定义 HTML 作为字符串。内容默认情况下将被解析为纯文本。在可以使用自定义 HTML 之前，必须在 Ionic 配置中将 `innerHTMLTemplatesEnabled` 设置为 `true`。
属性	`message`
类型	`IonicSafeString ｜ string ｜ undefined`
默认值	`undefined`

mode

描述	模式决定要使用哪个平台样式。
属性	`mode`
类型	`"ios" ｜ "md"`
默认值	`undefined`

position

描述	Toast 在屏幕上的起始位置。可以使用 `positionAnchor` 属性进行进一步调整。
属性	`position`
类型	`"bottom" ｜ "middle" ｜ "top"`
默认值	`'bottom'`

positionAnchor

描述	要将 Toast 的位置锚定到的元素。可以设置为直接引用或元素的 ID。如果 `position="bottom"`，则 Toast 将位于所选元素之上。如果 `position="top"`，则 Toast 将位于所选元素之下。如果 `position="middle"`，则 `positionAnchor` 的值将被忽略。
属性	`position-anchor`
类型	`HTMLElement ｜ string ｜ undefined`
默认值	`undefined`

swipeGesture

描述	如果设置为 'vertical'，则可以使用滑动手势来关闭 Toast。滑动方向由 `position` 属性的值决定：`top`：可以使用向上滑动来关闭 Toast。`bottom`：可以使用向下滑动来关闭 Toast。`middle`：可以使用向上或向下滑动来关闭 Toast。
属性	`swipe-gesture`
类型	`"vertical" ｜ undefined`
默认值	`undefined`

translucent

描述	如果为 `true`，则 Toast 将是半透明的。仅在模式为 `"ios"` 且设备支持 `backdrop-filter` 时适用。
属性	`translucent`
类型	`boolean`
默认值	`false`

trigger

描述	与触发元素的 ID 相对应，该触发元素在被点击时会导致 Toast 打开。
属性	`trigger`
类型	`string ｜ undefined`
默认值	`undefined`

事件

名称	描述	冒泡
`didDismiss`	Toast 消失后发出。ionToastDidDismiss 的简写。	`true`
`didPresent`	Toast 显示后发出。ionToastWillDismiss 的简写。	`true`
`ionToastDidDismiss`	Toast 消失后发出。	`true`
`ionToastDidPresent`	Toast 显示后发出。	`true`
`ionToastWillDismiss`	Toast 消失之前发出。	`true`
`ionToastWillPresent`	Toast 显示之前发出。	`true`
`willDismiss`	Toast 消失之前发出。ionToastWillDismiss 的简写。	`true`
`willPresent`	Toast 显示之前发出。ionToastWillPresent 的简写。	`true`

方法

dismiss

描述	在 Toast 叠加层显示后将其关闭。
签名	`dismiss(data?: any, role?: string) => Promise<boolean>`

onDidDismiss

描述	返回一个 Promise，该 Promise 在 Toast 消失时解析。
签名	`onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

onWillDismiss

描述	返回一个 Promise，该 Promise 在 Toast 将要消失时解析。
签名	`onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

present

描述	在创建 Toast 叠加层后将其显示。
签名	`present() => Promise<void>`

CSS 阴影部分

名称	描述
`button`	显示在 Toast 中的任何按钮元素。
`button cancel`	显示在 Toast 中的任何具有“cancel”角色的按钮元素。
`container`	包含所有子元素的元素。
`header`	Toast 的标题文本。
`icon`	出现在 Toast 内容旁边的图标。
`message`	Toast 的正文文本。

CSS 自定义属性

名称	描述
`--background`	Toast 的背景
`--border-color`	Toast 的边框颜色
`--border-radius`	Toast 的边框圆角
`--border-style`	Toast 的边框样式
`--border-width`	Toast 的边框宽度
`--box-shadow`	Toast 的盒子阴影
`--button-color`	按钮文本的颜色
`--color`	Toast 文本的颜色
`--end`	如果方向是从左到右，则为右侧的位置，如果方向是从右到左，则为左侧的位置
`--height`	Toast 的高度
`--max-height`	Toast 的最大高度
`--max-width`	Toast 的最大宽度
`--min-height`	Toast 的最小高度
`--min-width`	Toast 的最小宽度
`--start`	如果方向是从左到右，则为左侧的位置，如果方向是从右到左，则为右侧的位置
`--white-space`	Toast 消息的空白
`--width`	Toast 的宽度

名称	描述
`--background`	Toast 的背景
`--border-color`	Toast 的边框颜色
`--border-radius`	Toast 的边框圆角
`--border-style`	Toast 的边框样式
`--border-width`	Toast 的边框宽度
`--box-shadow`	Toast 的盒子阴影
`--button-color`	按钮文本的颜色
`--color`	Toast 文本的颜色
`--end`	如果方向是从左到右，则为右侧的位置，如果方向是从右到左，则为左侧的位置
`--height`	Toast 的高度
`--max-height`	Toast 的最大高度
`--max-width`	Toast 的最大宽度
`--min-height`	Toast 的最小高度
`--min-width`	Toast 的最小宽度
`--start`	如果方向是从左到右，则为左侧的位置，如果方向是从右到左，则为右侧的位置
`--white-space`	Toast 消息的空白
`--width`	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 阴影部分​

CSS 自定义属性​

插槽​

内容