通知消息

通过 toast、轻量级且易于自定义的警报消息向您的访问者推送通知。

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

概述

使用 toast 插件时要知道的事情:

  • 出于性能原因,Toast 是可选的,因此您必须自己初始化它们。
  • 如果您不指定 autohide: false,Toast 将自动隐藏。

该组件的动画效果依赖于 prefers-reduced-motion 媒体查询。请参阅我们可访问性文档的减少运动部分。

基本的

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

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分钟之前</small>
          <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
        </div>
        <div class="toast-body">
          《隋唐演义》既是中国古代一部白话小说,也是一部演绎历史风云、歌颂的经典传奇英雄之作。
        </div>
      </div>
以前,我们的脚本动态添加了 .hide 类来完全隐藏 toast(使用 display:none,而不仅仅是使用 opacity:0)。现在不再需要了。但是,为了向后兼容,我们的脚本将继续切换类(即使实际上没有必要),直到下一个主要版本。
在线示例

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

<button type="button" class="btn btn-primary" id="liveToastBtn">显示 toast</button>

      <div class="position-fixed bottom-0 end-0 p-3" style="z-index: 11">
        <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分钟之前</small>
            <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
          </div>
          <div class="toast-body">
            《历代诗话》,古代中国诗歌理论著作,诗话丛书。清代何文焕辑。
          </div>
        </div>
      </div>

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

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

          toast.show()
        })
      }
半透明

Toast 有点半透明,可以与下面的东西融为一体。

<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分钟之前</small>
          <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
        </div>
        <div class="toast-body">
          又名《真仙传道集》或《钟吕传道记》。五代,施肩吾整理。
        </div>
      </div>
堆叠

您可以通过将 toast 包装在 toast 容器中来堆叠,这将垂直增加一些间距。

<div class="toast-container">
        <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">刚刚</small>
            <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
          </div>
          <div class="toast-body">
            《管子》基本上是稷下道家推尊管仲之作的集结。即以此为稷下之学的管子学派。
          </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秒前</small>
            <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
          </div>
          <div class="toast-body">
            《绣花大盗》是武侠小说家古龙-陆小凤系列的第二个的故事。
          </div>
        </div>
      </div>
自定义内容

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

<div class="toast align-items-center" role="alert" aria-live="assertive" aria-atomic="true">
        <div class="d-flex">
          <div class="toast-body">
          《古今词话》是清初一部辑录类词话。
          </div>
          <button type="button" class="btn-close me-2 m-auto" data-bs-dismiss="toast" aria-label="Close"></button>
        </div>
      </div>

或者,您还可以向 toast 添加其他控件和组件。

<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
        <div class="toast-body">
          《吴越春秋》,东汉赵晔撰,是一部记述春秋时期吴、越两国史事为主的史学著作。
          <div class="mt-2 pt-2 border-top">
            <button type="button" class="btn btn-primary btn-sm">行动起来</button>
            <button type="button" class="btn btn-secondary btn-sm" data-bs-dismiss="toast">关闭</button>
          </div>
        </div>
      </div>
配色方案

在上述示例的基础上,您可以使用我们的颜色和背景实用程序创建不同的吐司配色方案。在这里,我们将 .bg-primary.text-white 添加到 .toast,然后将 .btn-close-white 添加到关闭按钮。对于清晰的边缘,我们使用 .border-0 删除默认边框。

<div class="toast align-items-center text-white bg-primary border-0" role="alert" aria-live="assertive" aria-atomic="true">
        <div class="d-flex">
          <div class="toast-body">
            《唐国史补》又称《国史补》,为中唐人李肇所撰。
          </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。右上角通常用于通知,顶部中间也是如此。如果您一次只显示一个 toast,请将定位样式放在 .toast 上。

Bootstrap 11分钟前
《靖康传信录》由李纲著,出自《旧唐书卷六十二列传第十二》。
<form>
        <div class="mb-3">
          <label for="selectToastPlacement">Toast 放置方式</label>
          <select class="form-select mt-2" id="selectToastPlacement">
            <option value="" selected>选择一个位置...</option>
            <option value="top-0 start-0">左上角</option>
            <option value="top-0 start-50 translate-middle-x">顶部中心</option>
            <option value="top-0 end-0">右上角</option>
            <option value="top-50 start-0 translate-middle-y">中左</option>
            <option value="top-50 start-50 translate-middle">水平垂直正中</option>
            <option value="top-50 end-0 translate-middle-y">中右</option>
            <option value="bottom-0 start-0">左下角</option>
            <option value="bottom-0 start-50 translate-middle-x">底部中心</option>
            <option value="bottom-0 end-0">右下角</option>
          </select>
        </div>
      </form>
      <div aria-live="polite" aria-atomic="true" class="bg-dark position-relative border-example-toasts">
        <div class="toast-container position-absolute 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分钟前</small>
            </div>
            <div class="toast-body">
              《靖康传信录》由李纲著,出自《旧唐书卷六十二列传第十二》。
            </div>
          </div>
        </div>
      </div>

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

<div aria-live="polite" aria-atomic="true" class="position-relative">
        <!-- 定位: -->
        <!-- - `.toast-container` 用于 toast 之间留间隔 -->
        <!-- - `.position-absolute`, `top-0` & `end-0` 把 toast 定位到右上角 -->
        <!-- - `.p-3` 防止 toast 粘在容器边缘  -->
        <div class="toast-container position-absolute top-0 end-0 p-3">

          <!-- 然后把 toast 放进去 -->
          <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">刚刚</small>
              <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
            </div>
            <div class="toast-body">
              《青红帮演义》讲述青红帮发展的历史。
            </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秒钟之前</small>
              <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
            </div>
            <div class="toast-body">
              《随园诗话》是袁枚的诗歌美学和诗歌理论著作。
            </div>
          </div>
        </div>
      </div>

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

<!-- 用于对齐 toast 的 Flexbox 容器 -->
      <div aria-live="polite" aria-atomic="true" class="d-flex justify-content-center align-items-center w-100">

        <!-- 然后在里面放toast -->
        <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分钟之前</small>
            <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
          </div>
          <div class="toast-body">
            《陶庵梦忆》为明朝散文家张岱所著。
          </div>
        </div>
      </div>
可访问性

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

请注意,在生成或更新 toast 之前,活动区域需要存在于标记中。如果同时动态生成两者并注入到页面中,一般不会被辅助技术公布。

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

随着您显示的内容发生变化,请务必更新延迟超时,以便用户有足够的时间阅读 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 时,您必须添加一个关闭按钮以允许用户关闭 toast。

上面的示例都是用的img(实际效果中是svg),这里header上用了字体图标,是为了展示其用法。
<div role="alert" aria-live="assertive" aria-atomic="true" class="toast" data-bs-autohide="false">
        <div class="toast-header">
          <i class="mdi mdi-information-outline me-2 fs-5 text-info"></i>
          <strong class="me-auto">Bootstrap</strong>
          <small>11分钟之前</small>
          <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
        </div>
        <div class="toast-body">
          元修《辽史》共116卷,包括本纪30卷,志32卷,表8卷,列传45卷,以及国语解1卷。
        </div>
      </div>

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

用法

通过 JavaScript 初始化 toast:

var toastElList = Array.prototype.slice.call(document.querySelectorAll('.toast'))
      var toastList = toastElList.map(function (toastEl) {
        return new bootstrap.Toast(toastEl, option)
      })
触发器

可以使用 toast 中按钮上的 data 属性来实现解除,如下所示:

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

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

<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=""

名称 类型 默认值 说明
animation boolean true 对 toast 应用 CSS 淡入淡出过渡
autohide boolean true 自动隐藏 toast
delay number 5000 延迟隐藏 toast (ms)
方法
异步方法和转换

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

show

显示元素的 toast。在 toast 实际显示之前(即在 shown.bs.toast 事件发生之前)返回给调用者。你必须手动调用这个方法,而不是你的 toast 不会显示。

toast.show()

hide

隐藏元素的 toast。在 toast 实际被隐藏之前(即在 hidden.bs.toast 事件发生之前)返回给调用者。如果您将自动隐藏设置为 false,则必须手动调用此方法。

toast.hide()

dispose

隐藏元素的 toast。您的 toast 将保留在 DOM 上,但不会再显示。

toast.dispose()

getInstance

允许您获取与 DOM 元素关联的 toast 实例的静态方法

var myToastEl = document.getElementById('myToastEl')
      var myToast = bootstrap.Toast.getInstance(myToastEl) // Returns a Bootstrap toast instance

getOrCreateInstance

静态方法,允许您获取与 DOM 元素关联的 toast 实例,或创建一个新实例以防它未初始化

var myToastEl = document.getElementById('myToastEl')
      var myToast = bootstrap.Toast.getOrCreateInstance(myToastEl) // Returns a Bootstrap toast instance
事件
时间类型 说明
show.bs.toast 此事件在调用 show 实例方法时立即触发。
shown.bs.toast 当 toast 对用户可见时触发此事件。
hide.bs.toast 当调用 hide 实例方法时,会立即触发此事件。
hidden.bs.toast 当 toast 完成对用户隐藏时触发此事件。
var myToastEl = document.getElementById('myToast')
      myToastEl.addEventListener('hidden.bs.toast', function () {
        // do something...
      })