吐司

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

🌐 Toasts are lightweight notifications designed to mimic the push notifications that have been popularized by mobile and desktop operating systems. They’re built with flexbox, so they’re easy to align and position.

概述

🌐 Overview

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

🌐 Things to know when using the toast plugin:

• 出于性能原因，Toast 是可选择启用的，因此你必须自己初始化它们。
• 如果你未指定 autohide: false，Toast 会自动隐藏。

示例

🌐 Examples

基本的

🌐 Basic

为了鼓励可扩展和可预测的提示，我们建议使用标题和正文。提示标题使用 display: flex，得益于我们的边距和 Flexbox 工具，可以轻松对齐内容。

🌐 To encourage extensible and predictable toasts, we recommend a header and body. Toast headers use display: flex, allowing easy alignment of content thanks to our margin and flexbox utilities.

吐司消息的灵活性很高，所需的标记也很少。至少，我们要求有一个元素来包含你的“吐司”内容，并强烈建议添加关闭按钮。

🌐 Toasts are as flexible as you need and have very little required markup. At a minimum, we require a single element to contain your “toasted” content and strongly encourage a dismiss button.

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

在线示例

🌐 Live example

单击下面的按钮可显示默认隐藏的 Toast（位于右下角的工具中）。

🌐 Click the button below to show a toast (positioned with our utilities in the lower right corner) that has been hidden by default.

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

🌐 We use the following JavaScript to trigger our live toast demo:

const toastTrigger = document.getElementById('liveToastBtn')
const toastLiveExample = document.getElementById('liveToast')

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

半透明

🌐 Translucent

Toast 略微透明，以便与其下方的内容融合。

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

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

堆叠

🌐 Stacking

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

🌐 You can stack toasts by wrapping them in a toast container, which will vertically add some spacing.

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

定制内容

🌐 Custom content

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

🌐 Customize your toasts by removing sub-components, tweaking them with utilities, or by adding your own markup. Here we’ve created a simpler toast by removing the default .toast-header, adding a custom hide icon from Bootstrap Icons, and using some flexbox utilities to adjust the layout.

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

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

🌐 Alternatively, you can also add additional controls and components to 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>

配色方案

🌐 Color schemes

基于上述示例，你可以使用我们的color和background工具创建不同的吐司颜色方案。在这里，我们将.text-bg-primary添加到.toast，然后将.btn-close-white添加到我们的关闭按钮。为了获得清晰的边缘，我们使用.border-0移除默认边框。

🌐 Building on the above example, you can create different toast color schemes with our color and background utilities. Here we’ve added .text-bg-primary to the .toast, and then added .btn-close-white to our close button. For a crisp edge, we remove the default border with .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>

放置

🌐 Placement

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

🌐 Place toasts with custom CSS as you need them. The top right is often used for notifications, as is the top middle. If you’re only ever going to show one toast at a time, put the positioning styles right on the .toast.

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

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

🌐 For systems that generate more notifications, consider using a wrapping element so they can easily stack.

<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 工具来水平和/或垂直对齐 Toast。

🌐 You can also get fancy with flexbox utilities to align toasts horizontally and/or vertically.

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

无障碍

🌐 Accessibility

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

🌐 Toasts are intended to be small interruptions to your visitors or users, so to help those with screen readers and similar assistive technologies, you should wrap your toasts in an aria-live region. Changes to live regions (such as injecting/updating a toast component) are automatically announced by screen readers without needing to move the user’s focus or otherwise interrupt the user. Additionally, include aria-atomic="true" to ensure that the entire toast is always announced as a single (atomic) unit, rather than just announcing what was changed (which could lead to problems if you only update part of the toast’s content, or if displaying the same toast content at a later point in time). If the information needed is important for the process, e.g. for a list of errors in a form, then use the alert component instead of toast.

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

🌐 Note that the live region needs to be present in the markup before the toast is generated or updated. If you dynamically generate both at the same time and inject them into the page, they will generally not be announced by assistive technologies.

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

🌐 You also need to adapt the role and aria-live level depending on the content. If it’s an important message like an error, use role="alert" aria-live="assertive", otherwise use role="status" aria-live="polite" attributes.

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

🌐 As the content you’re displaying changes, be sure to update the delay timeout so that users have enough time to read the 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 时，你必须添加一个关闭按钮，以允许用户关闭提示信息。

🌐 When using autohide: false, you must add a close button to allow users to dismiss the toast.

<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 的提示消息。

🌐 While technically it’s possible to add focusable/actionable controls (such as additional buttons or links) in your toast, you should avoid doing this for autohiding toasts. Even if you give the toast a long delay timeout, keyboard and assistive technology users may find it difficult to reach the toast in time to take action (since toasts don’t receive focus when they are displayed). If you absolutely must have further controls, we recommend using a toast with autohide: false.

CSS

变量

🌐 Variables

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

🌐 As part of Bootstrap’s evolving CSS variables approach, toasts now use local CSS variables on .toast for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

--#{$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 变量

🌐 Sass variables

$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;

用法

🌐 Usage

通过 JavaScript 初始化 toast：

🌐 Initialize toasts via JavaScript:

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

触发器

🌐 Triggers

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>

选项

🌐 Options

As options can be passed via data attributes or JavaScript, you can append an option name to data-bs-, as in data-bs-animation="{value}". Make sure to change the case type of the option name from “camelCase” to “kebab-case” when passing the options via data attributes. For example, use data-bs-custom-class="beautifier" instead of data-bs-customClass="beautifier".

As of Bootstrap 5.2.0, all components support an experimental reserved data attribute data-bs-config that can house simple component configuration as a JSON string. When an element has data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456 and the separate data attributes will override values given on data-bs-config. In addition, existing data attributes are able to house JSON values like data-bs-delay='{"show":0,"hide":150}'.

The final configuration object is the merged result of data-bs-config, data-bs-, and js object where the latest given key-value overrides the others.

方法

🌐 Methods

事件

🌐 Events

const myToastEl = document.getElementById('myToast')
myToastEl.addEventListener('hidden.bs.toast', () => {
  // do something...
})