跳至主要內容 跳至文件導覽
View on GitHub

通知訊息（Toasts）

使用通知訊息（一種輕量且易於自訂的警告訊息）向您的訪客推送通知。

本頁內容

通知訊息是輕量級的通知，設計模仿行動和桌面作業系統普及的推送通知。它們使用 Flexbox 建構，因此易於對齊和定位。

概覽（Overview）

使用通知訊息外掛程式時需要了解的事項：

  • 基於效能考量，通知訊息是選擇性啟用的，所以您必須自己初始化它們。
  • 如果您不指定 autohide: false，通知訊息將自動隱藏。

此元件的動畫效果取決於 prefers-reduced-motion 媒體查詢。請參閱我們無障礙文件中的減少動態效果章節。

範例（Examples）

基本（Basic）

為了鼓勵可擴展和可預測的通知訊息，我們建議使用標題區和內文。通知訊息標題區使用 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）。現在這不再必要了。然而，為了向後相容性，我們的腳本將繼續切換該類別（即使實際上不需要）直到下一個主要版本。

即時範例（Live example）

點擊下面的按鈕以顯示一個預設隱藏的通知訊息（使用我們的通用類別定位在右下角）。

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

透光（Translucent）

通知訊息略帶半透明，以便與下方的內容融合。

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>

堆疊（Stacking）

您可以將通知訊息包裹在通知訊息容器中來堆疊它們，這將垂直加入一些間距。

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>

自訂內容（Custom content）

透過移除子元件、使用通用類別調整它們，或加入您自己的標記來自訂您的通知訊息。這裡我們透過移除預設的 .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>

顏色方案（Color schemes）

在上述範例的基礎上，您可以使用我們的顏色和背景通用類別建立不同的通知訊息顏色方案。這裡我們在 .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>

位置（Placement）

根據您的需求使用自訂 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` 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>

無障礙（Accessibility）

通知訊息旨在對您的訪客或使用者造成小幅度的中斷，因此為了幫助使用螢幕閱讀器和類似輔助技術的人，您應該將通知訊息包裹在 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

變數（Variables）

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 變數（Sass variables）

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;

使用方式（Usage）

透過 JavaScript 初始化通知訊息：

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

觸發器（Triggers）

可以透過 toast 內部按鈕上的 data-bs-dismiss 屬性來實現關閉功能，如下所示： 

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

或者透過 toast 外部的按鈕，使用額外的 data-bs-target，如下所示： 

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

選項（Options）

由於選項可以透過 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 的合併結果，其中最後給定的鍵值對會覆寫其他的。

名稱類型預設值說明
animationbooleantrue對通知訊息套用 CSS 淡出過渡效果。
autohidebooleantrue在延遲後自動隱藏通知訊息。
delaynumber5000隱藏通知訊息前的延遲時間（毫秒）。

方法（Methods）

所有 API 方法都是非同步的，並會啟動一個過渡效果。 它們會在過渡開始後立即回傳給呼叫者，但在過渡結束之前。此外，對正在過渡中的元件進行方法呼叫將被忽略。在我們的 JavaScript 文件中了解更多。

方法說明
dispose隱藏元素的通知訊息。您的通知訊息將保留在 DOM 中但不會再顯示。
getInstance靜態方法，允許您取得與 DOM 元素關聯的通知訊息實例。
例如：const myToastEl = document.getElementById('myToastEl') const myToast = bootstrap.Toast.getInstance(myToastEl) 回傳 Bootstrap 通知訊息實例。
getOrCreateInstance靜態方法，允許您取得與 DOM 元素關聯的通知訊息實例，如果尚未初始化則建立新的。
const myToastEl = document.getElementById('myToastEl') const myToast = bootstrap.Toast.getOrCreateInstance(myToastEl) 回傳 Bootstrap 通知訊息實例。
hide隱藏元素的通知訊息。在通知訊息實際隱藏之前就回傳給呼叫者（即在 hidden.bs.toast 事件發生之前）。如果您將 autohide 設為 false，您必須手動呼叫此方法。
isShown根據通知訊息的可見性狀態回傳布林值。
show顯示元素的通知訊息。在通知訊息實際顯示之前就回傳給呼叫者（即在 shown.bs.toast 事件發生之前）。您必須手動呼叫此方法，否則您的通知訊息不會顯示。

事件（Events）

事件說明
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...
})