Skip to main content Skip to docs navigation
View on GitHub

吐司消息框（Toasts）

通过吐司向访客推送通知，这是一种轻量级、可轻松定制的警报信息。

On this page

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

概览

使用吐司插件的注意事项：

  • 出于性能方面的考虑，吐司是选择性的，因此您必须自行初始化它们 。
  • 如果不指定 “autohide: false”，吐司会自动隐藏。
该组件的动画效果取决于 prefers-reduced-motion 媒体查询。请参阅我们的可访问性文档中的缩减动作部分.

示例

基本

为促进吐司的可扩展性和可预测性，我们建议使用标题和正文。吐司标题使用 display: flex，借助我们的 margin 和 flexbox 工具，可以轻松对齐内容。 吐司可以根据您的需要灵活运用，所需的标记很少。我们至少需要一个元素来包含您的 “toasted” 内容，并强烈建议使用解散按钮。

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/partials/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()
  })
}

半透明

Toasts are slightly translucent to blend in with what’s below them.

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 Icons 中添加了一个自定义隐藏图标，并使用了一些 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>

配色方案

在上述示例的基础上，您可以使用 color 和 background 工具创建不同的吐司颜色方案。在这里，我们为 .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 mins ago
Hello, world! This is a toast message.
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` 用于吐司消息框之间的间隔  -->
  <!-- - `top-0` & `end-0` 将吐司消息框置于右上角 -->
  <!-- - `.p-3` 防止吐司粘在容器边缘  -->
  <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" 可确保整个吐司始终作为一个单一（原子）单元公布，而不是只公布更改的内容（如果只更新吐司的部分内容，或在稍后时间点显示相同的吐司内容，可能会导致问题）。如果所需的信息对进程非常重要，例如表单中的错误列表，那么请使用 alert 组件 而不是吐司。

请注意，在生成或更新吐司之前，实时区域必须存在于标记中。如果同时动态生成这两个区域并将其注入页面，辅助技术一般不会公布它们。

您还需要根据内容调整 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

变量

Added in v5.2.0

作为 Bootstrap 不断发展的 CSS 变量方法的一部分，吐司现在使用 .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 初始化吐司：

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

触发器

Dismissal can be achieved with the data-bs-dismiss attribute on a button within the toast as demonstrated below:

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

or on a button outside the toast using the additional data-bs-target as demonstrated below:

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

选项

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

从 Bootstrap 5.2.0 开始，所有组件都支持一个实验性预留data 属性 data-bs-config ，它可以将简单的组件配置以 JSON 字符串的形式存放。当一个元素具有data-bs-config='{“delay”:0, “title”:123}' 和 data-bs-title=“456” 属性时，最终的title值将是456，而单独的data 属性将覆盖data-bs-config上给出的值。此外，现有的data 属性还能容纳 JSON 值，如 data-bs-delay='{“show”:0, “hide”:150}'。

最终配置对象是 data-bs-config、data-bs- 和 js object 的合并结果，其中最新给定的键值优先于其他键值。

Name Type Default Description
animation boolean true 为吐司应用 CSS 淡入淡出过渡。
autohide boolean true 延迟后自动隐藏吐司。
delay number 5000 隐藏吐司前的延迟时间（毫秒）。

方法

所有 API 方法都是异步的，并且会启动一个过渡，它们会在过渡开始后、结束前返回给调用者。此外，对过渡组件的方法调用将被忽略。更多信息，请参阅 JavaScript 文档
Method Description
dispose 隐藏元素的吐司。您的吐司将保留在 DOM 上，但不会再显示。
getInstance 静态方法，用于获取与 DOM 元素相关的吐司实例。
比如: const myToastEl = document.getElementById('myToastEl') const myToast = bootstrap.Toast.getInstance(myToastEl) 返回一个 Bootstrap toast 实例。
getOrCreateInstance 静态方法，用于获取与 DOM 元素相关的吐司实例，或在未初始化的情况下创建一个新的吐司实例。
const myToastEl = document.getElementById('myToastEl') const myToast = bootstrap.Toast.getOrCreateInstance(myToastEl) 返回一个 Bootstrap toast 实例。
hide 隐藏元素的吐司。在吐司实际隐藏之前（即在发生 hidden.bs.toast 事件之前）返回给调用者。如果将 autohide 设为 false，则必须手动调用此方法。
isShown 根据吐司的可见性状态返回一个布尔值。
show 显示元素的祝酒词。在吐司实际显示之前（即在 shown.bs.toast 事件发生之前）返回给调用者。您必须手动调用此方法，否则您的吐司将不会显示。

事件

Event Description
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...
})