Skip to main content Skip to docs navigation
View on GitHub

吐司 (Toasts)

透過吐司向使用者推播通知，它是一種輕量且易於客製化的警報消息

六角學院的 Bootstrap 5 課程上線囉，立即與萬人一同學習最專業、最深入的 Bootstrap 5 課程。

立即上課去
On this page

吐司是輕量級通知，目的在於模仿行動版和桌面版作業系統的推播通知。它們是用 flexbox 構建的，因此很容易對齊和定位。

概觀

使用吐司元件時應瞭解的事情如下：

  • 出於效能原因吐司是選擇性加入的，所以您必須自己將它們初始化。
  • 如果你沒有指定 autohide: false，吐司會自動隱藏。
該元件的動畫效果取決於 prefers-reduced-motion media queries。請參考 reduced motion section of our accessibility documentation

範例

基礎

為了支援可擴充性和可預測性的吐司，我們建議加入標題和正文。 基於我們的 margin 和 flexbox 通用類別，吐司的標題使用 display:flex 輕鬆就能對齊內容。

吐司元件可靈活的配合需要，並且只需要很少的標記。我們至少需要一個單獨的元素來包裝您 “套用吐司樣式” 的內容，並強烈建議加上關閉按鈕。

<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 類別來完全隱藏 toast (使用 display:none，而不僅使用 opacity:0)。這現在不需要了。然而，為了向後兼容，我們的腳本將繼續切換類別 (即使沒有實際需要) 直到下一個主要版本。

Live example

點擊下面的按鈕來顯示預設情況下隱藏的 toast (位於右下角)。

<button type="button" class="btn btn-primary" id="liveToastBtn">Show live 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 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 來觸發我們的動態 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 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>

堆疊

可以透過將吐司包裝於 toast container 來推疊它們，這將會在垂直方向上增加一些間距。

<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">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-muted">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。以下我們透過移除預設的 .toast-header，從 Bootstrap Icons 添加一個自定義的隱藏 icon，並使用一些 flexbox 通用類別 調整排版。

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

另外，您也可以在吐司添加額外的控制項與元件。

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

配色方案

基於以上的範例，您也可以透過我們的 顏色 和 背景 通用類別。以下我們將 .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">
      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. 
<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-dark position-relative bd-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 mins ago</small>
      </div>
      <div class="toast-body">
        Hello, world! This is a toast message.
      </div>
    </div>
  </div>
</div>

對於會推播更多通知的系統，請考慮使用包裝元素的方式，讓它們可以堆疊顯示。

<div aria-live="polite" aria-atomic="true" class="position-relative">
  <!-- Position it: -->
  <!-- - `.toast-container` for spacing between toasts -->
  <!-- - `.position-absolute`, `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 position-absolute 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-muted">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-muted">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 通用類別來對吐司做水平 和/或 垂直的對齊。

<!-- 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 region 中。螢幕閱讀器會自動讀出 live region 中的改變 (例如：插入 / 更新吐司元件)，而不需要轉移用戶的焦點或以其他方式中斷用戶。另外，加入 aria-atomic="true" 以確保整個吐司元件都會被讀取為單一個（atomic）單位，而不只是讀出改變的部分 (如果你只更新部分吐司的內容，或者在稍後的時間點顯示相同的吐司內容，將可能會導致問題)。如果所要顯示的訊息對於該處理程序是很重要的，例如：表單中的錯誤列表，請使用 警報 (Alerts) 元件而不是吐司。

請注意，在生成或更新吐司之前，必須在標記中包含活動區域 (live region)。如果您同時動態生成兩者並將它們插入頁面，則輔助技術通常不會讀出它們。

你還需要根據內容調整 role 和 aria-live 的等級。如果它是一個重要的訊息，例如：錯誤訊息，請使用 role="alert" aria-live="assertive"，否則請使用 role="status" aria-live="polite" 屬性。

當您顯示的內容有改變時，請務必更新 delay timeout 以確保使用者有足夠的時間閱讀吐司。

<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 時，必須增加一個關閉的按鈕，讓用戶可以關閉吐司。

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

雖然從技術上來講可以在 toast 添加 可聚焦/可操作 的控件 (例如附加按鈕或是連結)，但您應該避免在自動隱藏的 toast 這樣做。即使你給 toast 一個很長的 delay timeout，鍵盤和輔助技術使用者可能會發現很難及時找到 toast 來採取行動 (因為 toast 在顯示時沒有獲得焦點)。如果你必須有進一步的控制，我們建議使用帶有 autohide: false 的 toast。

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($white, .85);
$toast-border-width:                1px;
$toast-border-color:                rgba($black, .1);
$toast-border-radius:               $border-radius;
$toast-box-shadow:                  $box-shadow;
$toast-spacing:                     $container-padding-x;

$toast-header-color:                $gray-600;
$toast-header-background-color:     rgba($white, .85);
$toast-header-border-color:         rgba($black, .05);

Usage

透過 JavaScript 啟用吐司:

var toastElList = [].slice.call(document.querySelectorAll('.toast'))
var toastList = toastElList.map(function (toastEl) {
  return new bootstrap.Toast(toastEl, option)
})

Triggers

Dismissal can be achieved with the data 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 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>

選項

選項可以透過資料屬性或是 JavaScript 傳遞。對於資料屬性，將選項名稱附加到 data-bs-，如： data-bs-animation=""。

Name Type Default Description
animation boolean true 在吐司應用 CSS fade 轉換效果
autohide boolean true 自動將吐司隱藏
delay number 5000 延遲隱藏吐司 (ms)

方法

Asynchronous methods and transitions

All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started but before it ends. In addition, a method call on a transitioning component will be ignored.

See our JavaScript documentation for more information.

展示

展示一個元素的吐司。在吐司實際被展示前回傳給調用者 (即在 shown.bs.toast 事件發生前)。 你必須手動調用此方法，否則吐司不會被展示。

toast.show()

隱藏

隱藏吐司的元素。 **在吐司元素實際隱藏之前 (即在 hidden.bs.toast 事件發生之前) 回傳給調用者。如果讓 autohide 等於 false，你必須手動調用這個方法。

toast.hide()

移除

隱藏一個元素的吐司。您的吐司元件將保留在 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 當使用者可看見吐司元素時，會觸發此事件。
hide.bs.toast 當調用 hide 方法時，此事件會立即觸發。
hidden.bs.toast 當對使用者隱藏了一個吐司元素時，會觸發此事件 
var myToastEl = document.getElementById('myToast')
myToastEl.addEventListener('hidden.bs.toast', function () {
  // do something...
})