Skip to main content Skip to docs navigation

通过 toast 向您的访客推送通知,这是一种轻量级且易于自定义的警报消息。

Toast 是轻量级通知,旨在模仿移动和桌面操作系统普及的推送通知。它们是用 flexbox 构建的,所以它们很容易对齐和定位。

概述

使用 toast 插件需要注意的事项:

  • 出于性能原因,Toast 是可选的,因此您必须自己对其进行初始化
  • 如果您不指定,Toasts 将自动隐藏autohide: false
该组件的动画效果依赖于prefers-reduced-motion媒体查询。请参阅我们的辅助功能文档的减少运动部分

例子

基本的

为了鼓励可扩展和可预测的 toast,我们建议使用标头和正文。Toast 标头使用display: flex,由于我们的 margin 和 flexbox 实用程序,可以轻松对齐内容。

Toast 可以根据您的需要灵活调整,并且需要的标记很少。至少,我们需要一个元素来包含您的“toasted”内容,并强烈建议使用关闭按钮。

网页格式
<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-header">
    <img src="..." class="rounded me-2" alt="...">
    <strong class="me-auto">Bootstrap</strong>
    <small>11 mins ago</small>
    <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>
以前,我们的脚本动态添加.hide类以完全隐藏 toast(使用display:none,而不仅仅是使用opacity:0)。现在不再需要了。然而,为了向后兼容,我们的脚本将继续切换类(即使没有实际需要)直到下一个主要版本。

实例

单击下面的按钮以显示默认情况下隐藏的 toast(与我们的实用程序一起位于右下角)。

<button type="button" class="btn btn-primary" id="liveToastBtn">Show live toast</button>

<div class="toast-container position-fixed bottom-0 end-0 p-3">
  <div id="liveToast" class="toast" role="alert" aria-live="assertive" aria-atomic="true">
    <div class="toast-header">
      <img src="..." class="rounded me-2" alt="...">
      <strong class="me-auto">Bootstrap</strong>
      <small>11 mins ago</small>
      <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
    </div>
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
  </div>
</div>

我们使用以下 JavaScript 来触发我们的 live toast 演示:

const toastTrigger = document.getElementById('liveToastBtn')
const toastLiveExample = document.getElementById('liveToast')
if (toastTrigger) {
  toastTrigger.addEventListener('click', () => {
    const toast = new bootstrap.Toast(toastLiveExample)

    toast.show()
  })
}

半透明

Toasts 略微半透明,以便与下面的东西融为一体。

网页格式
<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-header">
    <img src="..." class="rounded me-2" alt="...">
    <strong class="me-auto">Bootstrap</strong>
    <small class="text-muted">11 mins ago</small>
    <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>

堆叠

您可以通过将吐司包裹在吐司容器中来堆叠吐司,这会在垂直方向上增加一些间距。

网页格式
<div class="toast-container position-static">
  <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
    <div class="toast-header">
      <img src="..." class="rounded me-2" alt="...">
      <strong class="me-auto">Bootstrap</strong>
      <small class="text-muted">just now</small>
      <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
    </div>
    <div class="toast-body">
      See? Just like this.
    </div>
  </div>

  <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
    <div class="toast-header">
      <img src="..." class="rounded me-2" alt="...">
      <strong class="me-auto">Bootstrap</strong>
      <small class="text-muted">2 seconds ago</small>
      <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
    </div>
    <div class="toast-body">
      Heads up, toasts will stack automatically
    </div>
  </div>
</div>

自定义内容

通过删除子组件、使用实用程序调整它们或添加您自己的标记来自定义您的 Toast。在这里,我们通过删除 default 创建了一个更简单的 toast ,从Bootstrap Icons.toast-header添加自定义隐藏图标,并使用一些flexbox 实用程序来调整布局。

网页格式
<div class="toast align-items-center" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="d-flex">
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
    <button type="button" class="btn-close me-2 m-auto" data-bs-dismiss="toast" aria-label="Close"></button>
  </div>
</div>

或者,您也可以向 toasts 添加额外的控件和组件。

网页格式
<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-body">
    Hello, world! This is a toast message.
    <div class="mt-2 pt-2 border-top">
      <button type="button" class="btn btn-primary btn-sm">Take action</button>
      <button type="button" class="btn btn-secondary btn-sm" data-bs-dismiss="toast">Close</button>
    </div>
  </div>
</div>

配色方案

基于以上示例,您可以使用我们的颜色背景实用程序创建不同的 toast 配色方案。在这里,我们添加.text-bg-primary.toast,然后添加.btn-close-white到我们的关闭按钮。为了获得清晰的边缘,我们删除了带有.border-0.

网页格式
<div class="toast align-items-center text-bg-primary border-0" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="d-flex">
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
    <button type="button" class="btn-close btn-close-white me-2 m-auto" data-bs-dismiss="toast" aria-label="Close"></button>
  </div>
</div>

放置

根据需要使用自定义 CSS 放置祝酒词。右上角通常用于通知,中上角也是。如果您一次只显示一个祝酒词,请将定位样式放在.toast.

引导程序 11 分钟前
你好世界!这是祝酒词。
网页格式
<form>
  <div class="mb-3">
    <label for="selectToastPlacement">Toast placement</label>
    <select class="form-select mt-2" id="selectToastPlacement">
      <option value="" selected>Select a position...</option>
      <option value="top-0 start-0">Top left</option>
      <option value="top-0 start-50 translate-middle-x">Top center</option>
      <option value="top-0 end-0">Top right</option>
      <option value="top-50 start-0 translate-middle-y">Middle left</option>
      <option value="top-50 start-50 translate-middle">Middle center</option>
      <option value="top-50 end-0 translate-middle-y">Middle right</option>
      <option value="bottom-0 start-0">Bottom left</option>
      <option value="bottom-0 start-50 translate-middle-x">Bottom center</option>
      <option value="bottom-0 end-0">Bottom right</option>
    </select>
  </div>
</form>
<div aria-live="polite" aria-atomic="true" class="bg-body-secondary position-relative bd-example-toasts rounded-3">
  <div class="toast-container p-3" id="toastPlacement">
    <div class="toast">
      <div class="toast-header">
        <img src="..." class="rounded me-2" alt="...">
        <strong class="me-auto">Bootstrap</strong>
        <small>11 mins ago</small>
      </div>
      <div class="toast-body">
        Hello, world! This is a toast message.
      </div>
    </div>
  </div>
</div>

对于生成更多通知的系统,请考虑使用包装元素,以便它们可以轻松堆叠。

网页格式
<div aria-live="polite" aria-atomic="true" class="position-relative">
  <!-- Position it: -->
  <!-- - `.toast-container` for spacing between toasts -->
  <!-- - `top-0` & `end-0` to position the toasts in the upper right corner -->
  <!-- - `.p-3` to prevent the toasts from sticking to the edge of the container  -->
  <div class="toast-container top-0 end-0 p-3">

    <!-- Then put toasts within -->
    <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
      <div class="toast-header">
        <img src="..." class="rounded me-2" alt="...">
        <strong class="me-auto">Bootstrap</strong>
        <small class="text-muted">just now</small>
        <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
      </div>
      <div class="toast-body">
        See? Just like this.
      </div>
    </div>

    <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
      <div class="toast-header">
        <img src="..." class="rounded me-2" alt="...">
        <strong class="me-auto">Bootstrap</strong>
        <small class="text-muted">2 seconds ago</small>
        <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
      </div>
      <div class="toast-body">
        Heads up, toasts will stack automatically
      </div>
    </div>
  </div>
</div>

您还可以使用 flexbox 实用程序来水平和/或垂直对齐 toast。

网页格式
<!-- Flexbox container for aligning the toasts -->
<div aria-live="polite" aria-atomic="true" class="d-flex justify-content-center align-items-center w-100">

  <!-- Then put toasts within -->
  <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
    <div class="toast-header">
      <img src="..." class="rounded me-2" alt="...">
      <strong class="me-auto">Bootstrap</strong>
      <small>11 mins ago</small>
      <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
    </div>
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
  </div>
</div>

辅助功能

Toasts 旨在对您的访问者或用户造成小的干扰,因此为了帮助那些使用屏幕阅读器和类似辅助技术的人,您应该将 toasts 包装在一个aria-live区域中。屏幕阅读器会自动宣布活动区域的更改(例如注入/更新 toast 组件),无需移动用户的焦点或以其他方式打扰用户。此外,包括aria-atomic="true"确保整个 toast 始终作为单个(原子)单元宣布,而不是仅仅宣布更改的内容(如果您仅更新部分 toast 内容,或者如果显示相同的 toast 内容,这可能会导致问题在稍后的时间点)。如果所需的信息对流程很重要,例如表单中的错误列表,则使用警报组件而不是吐司。

请注意,在生成或更新 toast之前,活动区域需要出现在标记中。如果您同时动态生成两者并将它们注入到页面中,它们通常不会被辅助技术公布。

您还需要根据内容调整rolearia-live级别。如果是错误之类的重要消息,请使用role="alert" aria-live="assertive",否则使用role="status" aria-live="polite"属性。

当您显示的内容发生变化时,请务必更新delay超时,以便用户有足够的时间阅读 toast。

<div class="toast" role="alert" aria-live="polite" aria-atomic="true" data-bs-delay="10000">
  <div role="alert" aria-live="assertive" aria-atomic="true">...</div>
</div>

使用时autohide: false,必须添加一个关闭按钮以允许用户关闭吐司。

网页格式
<div role="alert" aria-live="assertive" aria-atomic="true" class="toast" data-bs-autohide="false">
  <div class="toast-header">
    <img src="..." class="rounded me-2" alt="...">
    <strong class="me-auto">Bootstrap</strong>
    <small>11 mins ago</small>
    <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>

虽然从技术上讲可以在 toast 中添加可聚焦/可操作的控件(例如附加按钮或链接),但您应该避免为自动隐藏 toast 执行此操作。即使您为 toast 设置了较长的delay超时时间,键盘和辅助技术用户也可能会发现很难及时到达 toast 以采取行动(因为 toast 在显示时不会获得焦点)。如果您绝对必须有进一步的控制,我们建议使用 toast with autohide: false

CSS

变量

添加于 v5.2.0

作为 Bootstrap 不断发展的 CSS 变量方法的一部分,toasts 现在使用本地 CSS 变量.toast来增强实时定制。CSS 变量的值是通过 Sass 设置的,因此仍然支持 Sass 自定义。

  --#{$prefix}toast-zindex: #{$zindex-toast};
  --#{$prefix}toast-padding-x: #{$toast-padding-x};
  --#{$prefix}toast-padding-y: #{$toast-padding-y};
  --#{$prefix}toast-spacing: #{$toast-spacing};
  --#{$prefix}toast-max-width: #{$toast-max-width};
  @include rfs($toast-font-size, --#{$prefix}toast-font-size);
  --#{$prefix}toast-color: #{$toast-color};
  --#{$prefix}toast-bg: #{$toast-background-color};
  --#{$prefix}toast-border-width: #{$toast-border-width};
  --#{$prefix}toast-border-color: #{$toast-border-color};
  --#{$prefix}toast-border-radius: #{$toast-border-radius};
  --#{$prefix}toast-box-shadow: #{$toast-box-shadow};
  --#{$prefix}toast-header-color: #{$toast-header-color};
  --#{$prefix}toast-header-bg: #{$toast-header-background-color};
  --#{$prefix}toast-header-border-color: #{$toast-header-border-color};
  

Sass 变量

$toast-max-width:                   350px;
$toast-padding-x:                   .75rem;
$toast-padding-y:                   .5rem;
$toast-font-size:                   .875rem;
$toast-color:                       null;
$toast-background-color:            rgba(var(--#{$prefix}body-bg-rgb), .85);
$toast-border-width:                var(--#{$prefix}border-width);
$toast-border-color:                var(--#{$prefix}border-color-translucent);
$toast-border-radius:               var(--#{$prefix}border-radius);
$toast-box-shadow:                  var(--#{$prefix}box-shadow);
$toast-spacing:                     $container-padding-x;

$toast-header-color:                var(--#{$prefix}secondary-color);
$toast-header-background-color:     rgba(var(--#{$prefix}body-bg-rgb), .85);
$toast-header-border-color:         $toast-border-color;

用法

通过 JavaScript 初始化 toasts:

const toastElList = document.querySelectorAll('.toast')
const toastList = [...toastElList].map(toastEl => new bootstrap.Toast(toastEl, option))

触发器

解雇可以通过toastdata中按钮上的属性来实现,如下所示:

<button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>

或在toast 外的按钮上使用data-bs-target如下所示:

<button type="button" class="btn-close" data-bs-dismiss="toast" data-bs-target="#my-toast" aria-label="Close"></button>

选项

由于可以通过数据属性或 JavaScript 传递选项,因此您可以将选项名称附加到data-bs-,如data-bs-animation="{value}". 当通过数据属性传递选项时,确保将选项名称的大小写类型从“ camelCase ”更改为“ kebab-case ”。例如,使用data-bs-custom-class="beautifier"而不是data-bs-customClass="beautifier"

从 Bootstrap 5.2.0 开始,所有组件都支持实验性保留数据属性data-bs-config,该属性可以将简单的组件配置作为 JSON 字符串进行存储。当元素具有data-bs-config='{"delay":0, "title":123}'data-bs-title="456"属性时,最终title值将是456并且单独的数据属性将覆盖 上给出的值data-bs-config。此外,现有的数据属性能够容纳 JSON 值,例如data-bs-delay='{"show":0,"hide":150}'.

名称 类型 默认 描述
animation 布尔值 true 对 toast 应用 CSS 淡入淡出过渡。
autohide 布尔值 true 延迟后自动隐藏吐司。
delay 数字 5000 隐藏 toast 之前的延迟毫秒数。

方法

异步方法和转换

所有 API 方法都是异步的并开始一个转换它们会在转换开始但结束之前立即返回给调用者。此外,将忽略对转换组件的方法调用。

有关详细信息,请参阅我们的 JavaScript 文档

方法 描述
dispose 隐藏元素的吐司。你的 toast 将保留在 DOM 上,但不会再显示。
getInstance 允许您获取与 DOM 元素关联的 toast 实例的静态方法。
例如:const myToastEl = document.getElementById('myToastEl') const myToast = bootstrap.Toast.getInstance(myToastEl)返回一个 Bootstrap toast 实例。
getOrCreateInstance 允许您获取与 DOM 元素相关联的 toast 实例的静态方法,或者创建一个新的实例,以防它未被初始化。
const myToastEl = document.getElementById('myToastEl') const myToast = bootstrap.Toast.getOrCreateInstance(myToastEl)返回一个 Bootstrap toast 实例。
hide 隐藏元素的吐司。在 toast 实际被隐藏之前返回给调用者(即在hidden.bs.toast事件发生之前)。如果你想,你必须手动调用这个autohide方法false
isShown 根据 toast 的可见性状态返回一个布尔值。
show 显示元素的吐司。在 toast 实际显示之前返回给调用者(即在shown.bs.toast事件发生之前)。您必须手动调用此方法,否则您的 toast 将不会显示。

事件

事件 描述
hide.bs.toast hide调用实例方法时会立即触发此事件。
hidden.bs.toast 当 toast 完成对用户隐藏时将触发此事件。
show.bs.toast show调用实例方法时会立即触发此事件。
shown.bs.toast 当 toast 对用户可见时会触发此事件。
const myToastEl = document.getElementById('myToast')
myToastEl.addEventListener('hidden.bs.toast', () => {
  // do something...
})