版本：v7

ion-toast

Toast 是现代应用中常用的轻量通知。它可用于提供操作反馈或显示系统消息。Toast 会显示在应用内容之上，可以被应用关闭以恢复用户与应用交互。

内联 Toast（推荐）

直接在模板中编写 ion-toast 组件即可使用。这减少了为显示 Toast 所需连接的处理程序数量。

使用 `isOpen`

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

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

控制器式 Toast

关闭

Toast 旨在提供轻量通知，不应打断用户。因此，关闭 Toast 不应要求用户交互。

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

由于 Toast 不应打断用户，因此按下硬件返回按钮不会关闭 Toast。

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

Console

Console messages will appear here when logged from the example above.

定位

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

相对定位

如果 Toast 与导航元素（如页眉、页脚或浮动操作按钮（FAB））一起显示，默认情况下 Toast 可能会与这些元素重叠。这可以通过使用 positionAnchor 属性来修复，该属性接受元素引用或 ID。Toast 将相对于所选元素定位，当使用 position="top" 时出现在其下方，使用 position="bottom" 时出现在其上方。使用 position="middle" 时，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 内容。

接口

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

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`

事件

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`

方法

dismiss

Description	Dismiss the toast overlay after it has been presented.
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"`. 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.

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

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

插槽

No slots available for this component.

内联 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 自定义属性​

插槽​

Contents