彈出訊息

彈出訊息是一種輕量級的通知，旨在仿照行動與電腦作業系統普及的推播通知。

彈出訊息旨在造成訪客或使用者輕微的中斷，因此應該包含極簡、直截了當、非互動式的內容。請參閱下方的 輔助功能提示 部分，以取得有關使用方式的 重要 資訊。

簡介

為了促進彈出訊息的延伸和可預測性，建議提供標頭 (標題) 和本文。彈出訊息標頭使用 'display: flex' 樣式，利用 Bootstrap 的 margin 和 flexbox 工具程式類別，可以讓內容輕鬆對齊。

彈出訊息也會稍微透明，因此可以融入它們出現的任何位置。對於支援 backdrop-filter CSS 屬性的瀏覽器，還會嘗試模糊彈出訊息下方的元素。

<template>
  <div class="p-3 bg-secondary progress-bar-striped" style="min-height: 170px;">
    <b-button class="mb-2" variant="primary" @click="$bvToast.show('example-toast')">
      Show toast
    </b-button>
    <b-toast id="example-toast" title="BootstrapVue" static no-auto-hide>
      Hello, world! This is a toast message.
    </b-toast>
  </div>
</template>

<!-- toast-intro.vue -->

注意：在上述範例中，我們使用 static 屬性將彈出訊息直接呈現在文件之中，而非傳輸到 <b-toaster> 目標容器。而且，我們在最外層 <div> 中加入了類別 bg-secondary 和 progress-bar-striped，這種做法僅用於說明彈出訊息的透明度。

彈出訊息功能和注意事項

• 彈出訊息可以透過注入 this.$bvToast 物件依需求產生，或者手動使用 <b-toast> 元件建立。
• 標題是選項性質，但建議包含，標題顯示在 <strong> 元素內，除非使用 toast-title 插槽。
• 上方右側的關閉按鈕可以透過下列 no-close-button prop 移出。
• 會顯示一個標題列，除非你未提供標題並設定下列 no-close-button prop。
• 自動隱藏發生在 5000 毫秒後，可以透過下列 auto-hide-delay prop 進行變更，或使用下列 no-auto-hide prop 停用。
• 當自動隱藏啟用時，當你將指標移至提示時，自動隱藏倒數計時會暫停。你可以透過將下列 no-hover-pause prop 設定為 true 來停用此功能。
• 如果你停用自動隱藏功能，請避免隱藏關閉按鈕，或是在隱藏關閉按鈕時務必允許提示自動關閉。請參閱下方的 無障礙提示 區段以取得重要的使用資訊。
• 可以透過將下列 solid prop 設定為 true 來停用提示透明度。
• 提示會顯示在命名的 <b-toaster> 目標元件內部。BootstrapVue 附帶幾個預先定義的提示目標。提示會在顯示之前檢查文件中的已命名提示，並且會在找不到目標時動態建立已命名的提示目標。
• 提示目標使用 CSS 來完全定義以控制所包含 <b-toast> 元件的位置。
• 提示可以針對任何已命名的提示。
• 提示會包覆在具有 b-toast 類別的 <div> 中，以便在提示元件中顯示時支援 Vue 列表轉場。

BootstrapVue 使用 PortalVue 將提示傳輸至提示器中。

依需求提示

透過下列 this.$bvToast Vue 元件 執行個體注入，從應用程式的任何位置產生動態提示，而不需要在應用程式中配置 <b-toast> 元件。

使用 this.$bvToast.toast() 方法來產生依需求提示。該方法接受兩個參數

• message：提示內文的內容（字串或 VNodes 陣列的任一項）。必要。訊息為空的提示不會顯示。請參閱 進階使用 區段以取得將 VNodes 陣列當作訊息傳遞的範例。
• options：提供標題和/或其他設定選項的選用選項物件。 title 選項可以使用字串或 VNodes 陣列

選項參數會接受 <b-toast> 元件所接受的大部分 prop（除了 static 和 visible），以 camelCase 名稱格式，而非 kebab-case。

<template>
  <div>
    <b-button @click="makeToast()">Show Toast</b-button>
    <b-button @click="makeToast(true)">Show Toast (appended)</b-button>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        toastCount: 0
      }
    },
    methods: {
      makeToast(append = false) {
        this.toastCount++
        this.$bvToast.toast(`This is toast number ${this.toastCount}`, {
          title: 'BootstrapVue Toast',
          autoHideDelay: 5000,
          appendToast: append
        })
      }
    }
  }
</script>

<!-- toasts-bv-toast-example.vue -->

一旦使用 this.$bvToast.toast() 產生的提示被隱藏，它會自動被銷毀並從文件中移除。

附註

• 只有在使用完整的 BootstrapVue 外掛程式或 ToastPlugin 外掛程式時才可用 this.$bvToast 注入。如果僅匯入 b-toast 或 b-toaster 元件，則無法使用它。只匯入 $bvToast 注入，請使用 BVToastPlugin 外掛程式。
• 為每個 Vue 虛擬機器實例 (即每個實例化的元件) 建立一個新的 $bvToast 注入 (混合)，且無法透過直接存取 Vue.prototype 使用它，因為它需要存取實例的 this 和 $root 內容。
• 透過 this.$bvToast.toast() 產生的提示訊息是呼叫 this.$bvToast.toast() 方法的 Vue 執行個體的子代，且如果該 Vue 執行個體 (即您的元件或應用程式) 也被銷毀，將會被隱藏並銷毀。如果 vm 內容在 <router-view> 內，且 $route 改變，提示訊息也會被銷毀 (因為 <router-view> 的所有子代都被銷毀了。若要讓依需求提示訊息持續存在於路由 $route 的變更中，請使用 this.$root.$bvToast.toast() 來讓提示訊息的父代成為您應用程式的根目錄。
• 提示訊息需要一個訊息。空訊息的依需求提示訊息將不會顯示。

選項

提示訊息有各項選項可以控制它們的樣式和行為。選項可做為 <b-toast> 元件上的屬性，也可以做為傳遞給 this.$bvToast.toast() 的選項物件的屬性。將選項傳遞給 this.$bvToast.toast() 時，請使用元件屬性名稱的 camelCase 版本，也就是，使用 noAutoHide 代替 no-auto-hide。

標題

透過 title 選項將標題新增到提示訊息。就像提示訊息 message，標題可以是簡單的字串，也可以是 VNodes 的陣列。請參閱 進階使用 區段，了解如何傳遞 VNodes 陣列作為訊息和標題。

透明度

提示訊息預設具有半透明背景。若要停用預設透明度，只要將 solid 屬性設定為 true 即可，以從背景顏色中移除 Alpha 通道。

在使用 SCSS 檔案而非 CSS 檔案時，也可以透過 BootstrapVue 客製 SCSS 變數 $b-toast-background-opacity 變更透明度。請參閱 主題 說明區段。

變體

BootstrapVue 提示訊息提供客製 CSS 以定義顏色變體。變體遵循標準 Bootstrap v4 變體名稱。如果您有定義自訂 SCSS 的 Bootstrap 顏色主題變體，提示訊息自訂 SCSS 將會自動為您建立提示訊息變體 (請參閱 主題 說明區段)。

<template>
  <div>
    <b-button @click="makeToast()" class="mb-2">Default</b-button>
    <b-button variant="primary" @click="makeToast('primary')" class="mb-2">Primary</b-button>
    <b-button variant="secondary" @click="makeToast('secondary')" class="mb-2">Secondary</b-button>
    <b-button variant="danger" @click="makeToast('danger')" class="mb-2">Danger</b-button>
    <b-button variant="warning" @click="makeToast('warning')" class="mb-2">Warning</b-button>
    <b-button variant="success" @click="makeToast('success')" class="mb-2">Success</b-button>
    <b-button variant="info" @click="makeToast('info')" class="mb-2">Info</b-button>
  </div>
</template>

<script>
  export default {
    methods: {
      makeToast(variant = null) {
        this.$bvToast.toast('Toast body content', {
          title: `Variant ${variant || 'default'}`,
          variant: variant,
          solid: true
        })
      }
    }
  }
</script>

<!-- toast-variants.vue -->

提示訊息目標

BootstrapVue 內建以下「內建」提示訊息目標名稱 (以及在 SCSS 中定義的相關樣式)

• b-toaster-top-right
• b-toaster-top-left
• b-toaster-top-center
• b-toaster-top-full
• b-toaster-bottom-right
• b-toaster-bottom-left
• b-toaster-bottom-center
• b-toaster-bottom-full

<template>
  <div>
    <b-button @click="toast('b-toaster-top-right')" class="mb-2">b-toaster-top-right</b-button>
    <b-button @click="toast('b-toaster-top-left')" class="mb-2">b-toaster-top-left</b-button>
    <b-button @click="toast('b-toaster-top-center')" class="mb-2">b-toaster-top-center</b-button>
    <b-button @click="toast('b-toaster-top-full')" class="mb-2">b-toaster-top-full</b-button>
    <b-button @click="toast('b-toaster-bottom-right', true)" class="mb-2">b-toaster-bottom-right</b-button>
    <b-button @click="toast('b-toaster-bottom-left', true)" class="mb-2">b-toaster-bottom-left</b-button>
    <b-button @click="toast('b-toaster-bottom-center', true)" class="mb-2">b-toaster-bottom-center</b-button>
    <b-button @click="toast('b-toaster-bottom-full', true)" class="mb-2">b-toaster-bottom-full</b-button>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        counter: 0
      }
    },
    methods: {
      toast(toaster, append = false) {
        this.counter++
        this.$bvToast.toast(`Toast ${this.counter} body content`, {
          title: `Toaster ${toaster}`,
          toaster: toaster,
          solid: true,
          appendToast: append
        })
      }
    }
  }
</script>

<!-- toast-targets.vue -->

附註

• 針對 CSS 中未定義的烤吐司目標名稱，其預設會顯示於文件的底部，而非堆疊且無定位（附於 <body> 中包含類別名稱及 ID 並設定為烤吐司目標名稱的 <b-toaster>）。烤吐司的唯一預設樣式為 z-index 的 1100。
• 請避免在應用程式中同時使用 b-toaster-top-* 烤吐司或 b-toaster-bottom-* 烤吐司，否則可能會在小螢幕（即 xs）上遮蔽或重疊通知訊息。

首置和追加

預設會將烤吐司首置於指定烤吐司顯示列表中的最上方，其順序與烤吐司建立的順序相同。如需將新烤吐司追加至底部，請將 append-toast 屬性設定為 true。

自動隱藏

透過 auto-hide-delay 屬性變更自動隱藏延遲時間（單位：毫秒），其預設值為 5000（最小值為 1000）。或者，透過將 no-auto-hide 屬性設定為 true，完全停用自動隱藏功能。

在啟用自動隱藏時，將滑鼠指標懸停在烤吐司上將暫停自動隱藏計時器。當您將滑鼠指標移開烤吐司後，將繼續計數自動隱藏計時器。您可以透過將 no-hover-pause 屬性設定為 true，停用此功能。

關閉按鈕

烤吐司預設會包含用於在點選時隱藏烤吐司的關閉按鈕。將 no-close-button 屬性設定為 true，將避免發生此情況，並產生一個沒有預設關閉按鈕的烤吐司。

您仍然可以透過提供一個唯一的 ID，並使用 this.$bvToast.hide(id) 方法，為烤吐司建立一個自訂關閉按鈕，以隱藏特定的烤吐司

<template>
  <div>
    <b-button @click="showToast">Show Toast</b-button>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        count: 0
      }
    },
    methods: {
      showToast() {
        // Use a shorter name for `this.$createElement`
        const h = this.$createElement
        // Create a ID with a incremented count
        const id = `my-toast-${this.count++}`

        // Create the custom close button
        const $closeButton = h(
          'b-button',
          {
            on: { click: () => this.$bvToast.hide(id) }
          },
          'Close'
        )

        // Create the toast
        this.$bvToast.toast([$closeButton], {
          id: id,
          title: `Toast ${this.count}`,
          noCloseButton: true
        })
      }
    }
 }
</script>

<!-- toasts-advanced.vue -->

烤吐司角色

烤吐司的預設 role 屬性為 'alert'，而 aria-live 屬性為 'assertive'。對於用於簡易通知的烤吐司，請將 is-status 屬性設定為 true，這將會將 role 和 aria-live 屬性分別變更為 'status' 和 'polite'。

如需更多資訊，請參閱下方的 協助工具 區段。

連結

可以透過 href 和 to 屬性，將烤吐司內容轉換為連結 (<a>) 或 <router-link>（或 <nuxt-link>）。設定後，整個烤吐司內容將會變成一個連結。

<template>
  <div>
    <b-button @click="toast()">Toast with link</b-button>
  </div>
</template>

<script>
  export default {
    methods: {
      toast() {
        this.$bvToast.toast(`Toast with action link`, {
          href: '#foo',
          title: 'Example'
        })
      }
    }
  }
</script>

<!-- toast-link.vue -->

<b-toast> 元件

如果您有一個僅想要一次顯示單一烤吐司的自訂元件，請使用 <b-toast> 元件。可以在自訂元件或應用程式中的任何位置放置 <b-toast> 元件，而且它不會呈現元件（它們會呈現不會影響版面的註解佔位符節點）。

可透過 v-model (綁定到 visible prop) 讓提示訊息可見，或者使用元件的 show() 和 hide() 執行個體方法，或是透過 this.$bvToast.show(id) 和 this.$bvToast.hide(id) 方法顯示（需要在 <b-toast> 元件上設定一個唯一 ID）。

預設情況下會將提示訊息在 b-toaster-top-right <b-toaster> 元件中進行調度。如果 toaster prop 指定的烤麵包機文件尚不存在，會立即建立它。

可透過設定 static prop 為 true，強制 <b-toast> 就地出現在文件當中。仍然需要顯示並隱藏提示訊息，但它不會傳送至烤麵包機元件。

<template>
  <div>
    <b-button @click="$bvToast.show('my-toast')">Show toast</b-button>

    <b-toast id="my-toast" variant="warning" solid>
      <template #toast-title>
        <div class="d-flex flex-grow-1 align-items-baseline">
          <b-img blank blank-color="#ff5555" class="mr-2" width="12" height="12"></b-img>
          <strong class="mr-auto">Notice!</strong>
          <small class="text-muted mr-2">42 seconds ago</small>
        </div>
      </template>
      This is the content of the toast.
      It is short and to the point.
    </b-toast>
  </div>
</template>

<!-- toast-component.vue -->

插槽

• toast-title：取代預設標題元素的內容。
• default：提示訊息主體的內容

兩個插槽皆可選擇使用下列範圍縮小範圍

僅在使用 <b-toast> 元件時才可以使用插槽。

<b-toaster> 目標元件

<b-toaster> 元件提供提示訊息會顯示的容器（烤麵包機）。烤麵包機需要一個唯一名稱，而且可以針對特定已命名烤麵包機，設定提示訊息於其中顯示。

在多數情況下，你不需要直接使用此元件，因為 <b-toast> 會自動插入一個 <b-toaster> 元件（附加至 <body>）並使用請求的烤麵包機名稱，但前提是在文件中找不到。有時你可能想要明確在應用程式中放置烤麵包機。

烤麵包機 name 會變成已插入容器的 ID，且也會被用作已呈現烤麵包機容器的類別名稱。

烤麵包機定位和烤麵包機內部提示訊息的位置，完全由 CSS 類別（根據烤麵包機的名稱）驅動

下列「內建」烤麵包機名稱（以及關聯的樣式）定義在 BootstrapVue 的自訂 SCSS 中

• b-toaster-top-right
• b-toaster-top-left
• b-toaster-top-center
• b-toaster-top-full
• b-toaster-bottom-right
• b-toaster-bottom-left
• b-toaster-bottom-center
• b-toaster-bottom-full

上述烤麵包機會以堆疊（縱列格式）放置提示訊息，固定在視窗中（表示說它們將永遠在視窗內，不論視窗捲軸位置為何）。如果提示訊息多到超出視窗螢幕可擺放的數量，一些提示訊息會在視覺上被隱藏在螢幕外，直到其他提示訊息被關閉/隱藏。

<b-toast> 預設使用 b-toaster-top-right 烤麵包機。

附註

• 如果文件已經存在具有相同名稱的 <b-toaster>（由 <b-toast>、this.$bvToast.toast() 自動建立，或手動放置），那麼 <b-toaster> 會只呈現一個空的 <div> 元素並發布一個主控台警告。
• 如果手動放置 <b-toaster> 元件，請確保將其放置在應用程式根元素的底部，作為最後一個元素，這樣應用程式中的所有頁面都可以使用它。
• 如果針對烤麵包機名稱顯示一個新的提示訊息，則會自動重新建立已被銷毀的烤麵包機。
• 在大部分的使用狀況下，你不需要自行將 <b-toaster> 元件手動置入/建立於應用程式中，因為有需要時系統會自動產生。但如果你需要覆寫任何預設的浮動視窗設定，請確定將浮動視窗置入應用程式中不受路由變更影響的位置。

進階使用

當使用 this.$bvToast.toast(...) 方法產生浮動視窗時，你可能希望浮動視窗的內容不僅僅是一個文字訊息。正如 隨選浮動視窗 區段所述，你可以傳遞包含 VNodes 的陣列，做為更複雜內容的訊息和標題。

請記住，浮動視窗內容應簡潔明瞭。避免在浮動視窗中放置互動式元件或元素，因為這可能會為輔助技術使用者造成問題。請參閱下方 易用性 區段。

以下範例說明如何使用 Vue 的 this.$createElement() 方法來建立更複雜的浮動視窗內容

<template>
  <div>
    <b-button @click="showToast">Show Toast with custom content</b-button>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        count: 0
      }
    },
    methods: {
      showToast() {
        // Use a shorter name for this.$createElement
        const h = this.$createElement
        // Increment the toast count
        this.count++
        // Create the message
        const vNodesMsg = h(
          'p',
          { class: ['text-center', 'mb-0'] },
          [
            h('b-spinner', { props: { type: 'grow', small: true } }),
            ' Flashy ',
            h('strong', 'toast'),
            ` message #${this.count} `,
            h('b-spinner', { props: { type: 'grow', small: true } })
          ]
        )
        // Create the title
        const vNodesTitle = h(
          'div',
          { class: ['d-flex', 'flex-grow-1', 'align-items-baseline', 'mr-2'] },
          [
            h('strong', { class: 'mr-2' }, 'The Title'),
            h('small', { class: 'ml-auto text-italics' }, '5 minutes ago')
          ]
        )
        // Pass the VNodes as an array for message and title
        this.$bvToast.toast([vNodesMsg], {
          title: [vNodesTitle],
          solid: true,
          variant: 'info'
        })
      }
    }
 }
</script>

<!-- toasts-advanced.vue -->

警告和浮動視窗

有時你或許只會需要一個簡單的警告樣式訊息（例如 cookie 使用通知等等）。在這種情況下，通常建議使用固定位置警告，而不是浮動視窗，你可以使用幾個 Bootstrap 工具程式類別，並針對 <b-alert> 元件套用一些自訂樣式

<template>
  <div>
    <b-button size="sm" @click="showBottom = !showBottom">
      {{ showBottom ? 'Hide' : 'Show' }} Fixed bottom Alert
    </b-button>
    <b-alert
      v-model="showBottom"
      class="position-fixed fixed-bottom m-0 rounded-0"
      style="z-index: 2000;"
      variant="warning"
      dismissible
    >
      Fixed position (bottom) alert!
    </b-alert>

    <b-button size="sm" @click="showTop = !showTop">
      {{ showTop ? 'Hide' : 'Show' }} Fixed top Alert
    </b-button>
    <b-alert
      v-model="showTop"
      class="position-fixed fixed-top m-0 rounded-0"
      style="z-index: 2000;"
      variant="success"
      dismissible
    >
      Fixed position (top) alert!
    </b-alert>
  </div>
</template>

<script>
export default {
  data() {
    return {
      showBottom: false,
      showTop: false
    }
  }
}
</script>

<!-- fixed-position-alerts.vue -->

我們使用 position-fixed 類別把定位設定為使用者的視埠中的固定位置，並使用 fixed-bottom 或 fixed-top 類別把警告定位在視埠的底部或頂部。 m-0 類別會移除警告周圍的預設邊界，而 rounded-0 類別則會移除預設的圓弧角。我們也會將 z-index 設定為較大的數字，以確保警告會顯示在頁面上任何其他內容的前方（fixed-top 和 fixed-bottom 的預設值為 1030）。你可能需要為你的特定版面調整 z-index。

由於警告標記會保留在你放置 <b-alert> 元件的位置的 DOM 中，它的標籤順序（用於存取移除按鈕）便可以輕鬆讓螢幕讀取程式和只能用鍵盤的使用者使用。

易用性

浮動視窗的目的是對你的訪客或使用者造成輕微的干擾，因此為了協助有螢幕讀取程式和類似輔助技術的人士，浮動視窗會包裹在 aria-live 區域中。螢幕讀取程式會自動宣布對 live 區域的變更（例如插入/更新浮動視窗元件），而不需要移動使用者的焦點或以其他方式中斷使用者。此外，會自動設定 aria-atomic="true"，以確保永遠將整個浮動視窗宣布為單一（原子）單位，而不是宣布變更的內容（如果你只更新浮動視窗內容的部分內容，或者稍後顯示相同的浮動視窗內容，這可能會造成問題）。

如果你只需要一個簡單的訊息出現在使用者的視窗上方或下方，請改用 固定位置 <b-alert>。

易用性提示

通常，提示訊息應顯示不須使用者互動的單行或雙行非重要訊息。如果不採取額外步驟，提示訊息會產生許多無障礙問題，這可能會影響身心障礙者和非身心障礙者。下表並未提供完整資訊，僅作為使用提示訊息的一般指南。

• 如果所需的資訊對流程而言很重要（例如，表單中的錯誤清單），請使用 <b-alert> 元件，而非 <b-toast>。
• <b-toast> 預設將屬性 role 設為 'alert'，將 aria-live 設為 'assertive'。如果這是一則重要訊息（例如錯誤），此預設設定就是適當的。否則，將 prop is-status 設為 true，這樣會將屬性 role 變更為 'status'，並將 aria-live 變更為 'polite'。
• 避免在網頁載入時彈出提示訊息。在網頁載入時執行意外的動作，會讓螢幕閱讀器使用者非常困惑。如果在網頁載入或路由變更時需要提示訊息，請延後數秒再顯示提示訊息，如此一來螢幕閱讀器便可完成宣告有關目前網頁的資訊，而不會被提示訊息中斷。
• 在將 prop no-auto-hide 設為 true 時，您必須新增一個關閉按鈕以讓使用者可以關閉提示訊息。如果您還將 prop no-close-button 設為 true，您必須提供自己的關閉按鈕或以其他方式關閉提示訊息。提示訊息的 tab index 為 0，以便只能使用鍵盤的使用者可以觸及這些訊息。
• 避免快速連續啟動多個提示訊息，因為螢幕閱讀器可能會中斷正在朗讀的提示訊息，並宣告新的提示訊息，這會導致無法獲取前一個提示訊息的內容。
• 對於文字內容較長的提示訊息，請將 auto-hide-delay 調整為較長的逾時時間，以讓使用者有時間閱讀提示訊息的內容。一般人每分鐘大約可以閱讀 200 個字，因此，顯示訊息的適當時間長度為 5 秒，外加每個字元多 300 毫秒。最佳作法應以最短預設值 5 秒 (5000 毫秒) 為基準。除了合理的預設逾時時間外，您也可以讓使用者選擇他們想要的提示訊息顯示時間長度。大多數人都很了解自己閱讀速度快或慢。若訊息消失得太快，使用者的個人設定資料中提供此個人資料檔案設定，讓閱讀速度慢的人可以選擇較長的顯示時間；若訊息顯示時間過長，讓閱讀速度快的人可以選擇較短的顯示時間。
• 考量到記憶力衰退與分心，以及 ADHD 等身心障礙議題，最佳作法會是實作一個使用者可以參考過去顯示過的提示訊息清單的位置。最理想的狀態是這個清單應為可排序清單，預設為依時間順序排列。

Internet Explorer 螢幕閱讀器支援

很不幸地，當使用 NVDA 或 JAWS 螢幕閱讀器時，IE 11 無法正確宣告或朗讀提示訊息。如果您有許多在使用 IE 11 的視障使用者，您可能想要建立另一個畫外 aria-live 區域，這個區域只針對 IE 11 瀏覽器（在網頁載入時建立），其中會動態放置提示訊息文字的副本，並顯示提示訊息。