跳至主要内容 跳至文档导航
在 GitHub 上查看

Toasts

使用轻量且易于自定义的警报消息吐司向您的访问者推送通知。

此页面上

吐司是轻量级通知，旨在模仿移动和桌面操作系统中流行的推送通知。它们使用 flexbox 构建，因此易于对齐和定位。

概述

使用吐司插件时需要注意的事项

  • 出于性能原因，吐司是选择加入的，因此您必须自己初始化它们。
  • 如果您未指定 autohide: false，吐司将自动隐藏。
此组件的动画效果取决于 prefers-reduced-motion 媒体查询。请参阅无障碍文档中的减少运动部分。

示例

基础

为了促进可扩展且可预测的吐司，我们建议使用标题和正文。吐司标题使用 display: flex，借助我们的边距和 flexbox 实用程序，可以轻松对齐内容。

吐司具有您需要的灵活性，并且几乎不需要标记。至少，我们需要一个元素来包含您的“吐司”内容，并强烈建议使用关闭按钮。

html 
<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 类以完全隐藏吐司（使用 display:none，而不仅仅是使用 opacity:0）。现在不再需要这样做。但是，为了向后兼容，我们的脚本将继续切换该类（即使实际上不需要它），直到下一个主要版本。

实时示例

点击下面的按钮以显示一个吐司（使用我们的实用工具定位在右下角），该吐司默认情况下已隐藏。

<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 来触发我们的实时吐司演示

site/assets/js/snippets.js 
const toastTrigger = document.getElementById('liveToastBtn')
const toastLiveExample = document.getElementById('liveToast')

if (toastTrigger) {
  const toastBootstrap = bootstrap.Toast.getOrCreateInstance(toastLiveExample)
  toastTrigger.addEventListener('click', () => {
    toastBootstrap.show()
  })
}

半透明

吐司略带半透明，以便与它们下面的内容融为一体。

html 
<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-body-secondary">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>

堆叠

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

html 
<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-body-secondary">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-body-secondary">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-header、从 Bootstrap 图标 中添加一个自定义隐藏图标，并使用一些 flexbox 实用工具 来调整布局，创建了一个更简单的吐司。

html 
<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>

或者，你还可以向吐司中添加其他控件和组件。

html 
<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，然后向我们的关闭按钮添加了 .btn-close-white。为了获得清晰的边缘，我们使用 .border-0 移除默认边框。

html 
<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 上。

Bootstrap 11 分钟前
你好，世界！这是一条吐司消息。
html 
<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>

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

html 
<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-body-secondary">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-body-secondary">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 实用工具来对齐吐司的水平和/或垂直方向。

html 
<!-- 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>

辅助功能

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

请注意，实时区域需要在吐司生成或更新之前出现在标记中。如果您同时动态生成两者并将它们注入到页面中，则辅助技术通常不会播报它们。

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

随着您显示的内容发生变化，请务必更新 delay 超时，以便用户有足够的时间阅读吐司。

<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 时，您必须添加一个关闭按钮以允许用户关闭吐司。

html 
<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>

虽然从技术上讲，可以在吐司中添加可聚焦/可操作的控件（例如其他按钮或链接），但您应该避免对自动隐藏吐司执行此操作。即使您给吐司一个很长的 delay 超时，键盘和辅助技术用户也可能很难及时到达吐司以采取措施（因为吐司在显示时不会接收焦点）。如果您绝对必须有更多控件，我们建议使用 autohide: false 的吐司。

CSS

变量

在 v5.2.0 中添加

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

scss/_toasts.scss 
--#{$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 变量

scss/_variables.scss 
$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 初始化 Toast

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

触发器

关闭可以通过 Toast 中 的按钮上的 data-bs-dismiss 属性实现，如下所示

<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="{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}'。

最终的配置对象是 data-bs-config、data-bs- 和 js 对象 的合并结果，其中最新给出的键值覆盖其他键值。

名称 类型 默认值 说明
动画 布尔值 真 对吐司应用 CSS 渐隐过渡。
自动隐藏 布尔值 真 在延迟后自动隐藏吐司。
延迟 数字 5000 隐藏吐司之前的延迟（以毫秒为单位）。

方法

所有 API 方法都是异步的，并启动一个过渡。它们在过渡启动后立即返回调用方，但在过渡结束之前返回。此外，将忽略对正在过渡的组件的方法调用。 在我们的 JavaScript 文档中了解更多信息。
方法 说明
dispose 隐藏元素的吐司。您的吐司将保留在 DOM 中，但不再显示。
getInstance 静态方法，允许您获取与 DOM 元素关联的吐司实例。
例如：const myToastEl = document.getElementById('myToastEl') const myToast = bootstrap.Toast.getInstance(myToastEl) 返回引导程序吐司实例。
getOrCreateInstance 静态方法，允许您获取与 DOM 元素关联的吐司实例，或者在未初始化的情况下创建一个新的吐司实例。
const myToastEl = document.getElementById('myToastEl') const myToast = bootstrap.Toast.getOrCreateInstance(myToastEl) 返回引导程序吐司实例。
hide 隐藏元素的吐司。在吐司实际隐藏之前返回给调用方（即在 hidden.bs.toast 事件发生之前）。如果您将 autohide 设置为 false，则必须手动调用此方法。
isShown 根据吐司的可见性状态返回布尔值。
show 显示元素的吐司。在吐司实际显示之前返回给调用方（即在 shown.bs.toast 事件发生之前）。您必须手动调用此方法，否则您的吐司将不会显示。

事件

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