跳到主要内容
输入关键词开始搜索，↑ ↓ 选择，Enter 打开
没有找到匹配的文档

消息提示

通过消息提示向你的访客发送推送通知，这是一种轻量且易于自定义的提示信息。

层级：components
查看原文
本页目录

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

概览

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

  • 为了性能考虑，Toast 是可选的，因此 你必须自己初始化它们。
  • 如果你没有指定 autohide: false，Toast 会自动隐藏。

此组件的动画效果取决于 prefers-reduced-motion 媒体查询。请参阅我们无障碍文档中的 减少动画部分。

示例

基础

为了鼓励可扩展且可预测的通知，我们建议使用标题和正文。通知标题使用 display: flex，借助我们的边距和弹性盒子工具，可以轻松对齐内容。

消息提示消息非常灵活，几乎不需要任何标记。最起码，我们要求一个单独的元素来包含你的“消息提示”内容，并强烈建议添加一个关闭按钮。

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="关闭"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>

现场示例

点击下面的按钮以显示一个默认隐藏的提示信息（使用我们的工具类定位在右下角）。

HTML
          <button type="button" class="btn-solid theme-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>
      <CloseButton dismiss="toast" />
    </div>
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
  </div>
</div>

我们使用以下 JavaScript 来触发我们的实时 toast 演示：

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

if (toastTrigger) {
  const toastBootstrap = 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="fg-2">11 mins ago</small>
    <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="关闭"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>

添加 .toast-translucent 以通过背景模糊和饱和度滤镜增强透明度。

HTML
<div class="toast toast-translucent" 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="fg-2">11 mins ago</small>
    <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="关闭"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a translucent 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="fg-2">just now</small>
      <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="关闭"></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="fg-2">2 seconds ago</small>
      <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="关闭"></button>
    </div>
    <div class="toast-body">
      Heads up, toasts will stack automatically
    </div>
  </div>
</div>

深色消息提示

为暗黑模式干杯，方法是添加 data-bs-theme="dark" 归因于 .toast 元素。

HTML
<div class="toast" data-bs-theme="dark" 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="opacity-60">2 seconds ago</small>
    <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="关闭"></button>
  </div>
  <div class="toast-body">
    This toast is in dark mode by default.
    <div class="hstack gap-2 mt-2">
      <button type="button" class="btn-solid theme-primary btn-sm">Take action</button>
      <button type="button" class="btn-solid theme-secondary btn-sm" data-bs-dismiss="toast">Close</button>
    </div>
  </div>
</div>

变体

消息提示可以使用我们的 主题颜色工具 来设置主题。可以应用于整个消息提示或消息提示内的单个元素。

HTML
<div class="toast theme-primary" 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="opacity-60">2 seconds ago</small>
    <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="关闭"></button>
  </div>
  <div class="toast-body">
    This toast is a primary themed toast.
    <div class="hstack gap-2 mt-2">
      <button type="button" class="btn-solid btn-sm">Take action</button>
      <button type="button" class="btn-solid theme-secondary btn-sm" data-bs-dismiss="toast">Close</button>
    </div>
  </div>
</div>

<div class="toast theme-accent" 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="opacity-60">2 seconds ago</small>
    <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="关闭"></button>
  </div>
  <div class="toast-body">
    This toast is an accent-themed toast.
    <div class="hstack gap-2 mt-2">
      <button type="button" class="btn-solid btn-sm">Take action</button>
      <button type="button" class="btn-solid theme-secondary btn-sm" data-bs-dismiss="toast">Close</button>
    </div>
  </div>
</div>

自定义内容

通过移除子组件、使用工具类进行调整，或添加你自己的标记来自定义你的提示。这里我们通过移除默认的.toast-header、添加来自Bootstrap 图标的自定义隐藏图标，以及使用一些Flexbox 工具类来调整布局，创建了一个更简单的提示。

HTML
<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="d-flex justify-content-between">
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
    <button type="button" class="btn-close me-3 m-auto" data-bs-dismiss="toast" aria-label="关闭"></button>
  </div>
</div>

或者，你也可以向提示添加额外的控件和组件。

HTML
<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-body">
    This is a custom toast message with additional content like a horizontal rule and buttons.
    <hr class="my-3" />
    <div class="hstack gap-2">
      <button type="button" class="btn-solid theme-primary btn-sm">Take action</button>
      <button type="button" class="btn-solid theme-secondary btn-sm" data-bs-dismiss="toast">Close</button>
    </div>
  </div>
</div>

即时

默认情况下，消息提示会淡入和淡出。要禁用动画，请将 .toast-instant 添加到消息提示中。然后 show 和 hide 方法会立即完成，因此 shown.bs.toast 和 hidden.bs.toast 会立即触发。

HTML
<div class="toast toast-instant" 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="关闭"></button>
  </div>
  <div class="toast-body">
    This toast appears and disappears instantly.
  </div>
</div>

职位安排

根据需要使用自定义 CSS 放置提示。右上角通常用于通知，中上位置也是如此。如果你只打算一次显示一个提示，请将定位样式直接放在 .toast 上。

Bootstrap 11分钟前
你好，世界！这是一条提示消息。
HTML
<form>
  <div class="mb-3">
    <label for="selectToastPlacement">Toast placement</label>
    <select class="form-control mt-2" id="selectToastPlacement">
      <option value="" selected disabled>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-1 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>

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

定位它： - `.toast-container` 用于设置各个 toast 之间的间距 - 使用 `top-0` 和 `end-0` 将弹出通知定位在右上角 - `.p-3` 防止提示框粘在容器边缘
然后把消息提示放进去
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="fg-2">just now</small>
        <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="关闭"></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="fg-2">2 seconds ago</small>
        <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="关闭"></button>
      </div>
      <div class="toast-body">
        Heads up, toasts will stack automatically
      </div>
    </div>
  </div>
</div>

你也可以使用 flexbox 工具来水平和/或垂直对齐 toast。

用于对齐提示的 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="关闭"></button>
    </div>
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
  </div>
</div>

无障碍访问

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

请注意，实时区域需要在生成或更新提示消息 之前 就存在于标记中。如果你同时动态生成两者并将其注入页面，它们通常不会被辅助技术宣布。

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

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

HTML
          <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="关闭"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>

虽然从技术上讲，可以在你的 toast 中添加可聚焦/可操作的控件（例如额外的按钮或链接），但你应该避免在自动消失的 toast 中这样做。即使你给 toast 设置了很长的 delay 超时时间，键盘和辅助技术用户也可能难以及时操作 toast（因为 toast 在显示时不会获得焦点）。如果你确实必须添加更多控件，我们建议使用带有 autohide: false 的 toast。

CSS

变量

消息提示在.toast上使用本地 CSS 变量进行实时定制。CSS 变量的值是从每个组件独有的 Sass map生成，并应用于上述类。

scss/_toasts.scss
// stylelint-disable custom-property-no-missing-var-function
// stylelint-disable-next-line scss/dollar-variable-default
$toast-tokens: defaults(
  (
    --toast-zindex: var(--z-toast),
    --toast-padding-x: 1rem,
    --toast-padding-y: .75rem,
    --toast-spacing: #{$container-padding-x},
    --toast-max-width: 350px,
    --toast-font-size: var(--font-size-sm),
    --toast-color: null,
    --toast-bg: var(--bg-body),
    --toast-border-width: var(--border-width),
    --toast-border-color: var(--border-color-translucent),
    --toast-border-radius: null,
    --toast-box-shadow: var(--box-shadow),
    --toast-header-color: var(--fg-3),
    --toast-header-bg: var(--bg-1),
    --toast-header-border-color: var(--border-color-translucent),
    --toast-transition-property: "opacity, display",
    --toast-transition-duration: .15s,
    --toast-transition-timing: linear,
  ),
  $toast-tokens
);
// stylelint-enable custom-property-no-missing-var-function

用法

通过 JavaScript 初始化提示：

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

通过数据属性

属性描述
data-bs-dismiss="toast"在关闭控件上，激活时会关闭 Toast 提示。
data-bs-autohideToast 提示是否在延迟后自动隐藏。
data-bs-delay隐藏之前的时间，单位为毫秒（当自动隐藏启用时）。

触发因素

解雇可以通过 data-bs-dismiss 按钮上的属性 消息提示里面 如下所示：

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

或者在 toast 之外的按钮上使用额外的 data-bs-target，如下所示：

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

依赖项

如果你从源代码构建 Bootstrap 的 JS，toast 插件需要以下 JavaScript 文件：

文件描述
js/src/toast.ts主消息提示组件
js/src/base-component.ts基础组件类
js/src/dom/data.ts元素数据存储
js/src/dom/event-handler.ts事件处理工具
js/src/dom/manipulator.ts数据属性操作
js/src/dom/selector-engine.tsDOM选择器工具
js/src/util/component-functions.ts共享组件助手
js/src/util/config.ts配置基类
js/src/util/index.ts核心实用功能

选项

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

所有组件都支持一个保留的数据属性 data-bs-config，该属性可以以 JSON 字符串的形式存放简单的组件配置。当一个元素具有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 属性时，最终的 title 值将是 456，并且单独的数据属性将覆盖在 data-bs-config 上给定的值。此外，现有的数据属性也可以存放像 data-bs-delay='{"show":0,"hide":150}' 这样的 JSON 值。

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

名称类型默认值描述
autohidebooleantrue在延迟后自动隐藏提示
delaynumber5000隐藏提示之前的延迟时间（毫秒）

方法

显示或隐藏组件的方法会返回一个 Promise。 当过渡结束时，该 Promise 会被解析，所以 await 会在 shown.bs.* 或 hidden.bs.* 监听器运行的同一时刻继续。方法仍会立即返回，并且永远不会阻塞调用者。对已在过渡中的组件进行调用不会有任何效果，并会立即解析。在我们的 JavaScript 文档中了解更多。

方法描述
dispose隐藏元素的提示。你的提示将保留在 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隐藏元素的提示信息。 返回一个在消息提示隐藏后解决的承诺 （即在……之后 hidden.bs.toast 事件触发）。如果你进行了修改，你必须手动调用此方法 autohide 到 false.
isShown根据 toast 的可见状态返回布尔值。
show显示元素的提示信息。 返回一个在消息提示显示后解决的承诺 （即在……之后 shown.bs.toast 事件触发）。你必须手动调用此方法，否则你的提示不会显示。

事件

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