工具提示 | 指令 | BootstrapVue 元件庫

將自訂的 BootstrapVue 工具提示加入任何元素中。工具提示可以透過游標移入、焦點或按一下元素來觸發。

概述

對你想要顯示工具提示的元素或元件使用 v-b-tooltip 指令。

<div class="text-center my-3">
  <b-button v-b-tooltip.hover title="Tooltip content">Hover Me</b-button>
</div>

<!-- b-tooltip.vue -->

使用工具提示指令時需要知道的事項

工具提示依賴第三方函式庫 Popper.js 來定位。
工具提示需要 BootstrapVue 的自訂 SCSS/CSS 才能正確運作，而且適用於變體。
若未提供標題 (或為空字串)，則不會顯示工具提示。
指定容器：'body' (預設值)，以避免在較複雜元件 (例如輸入群組、按鈕群組等) 中出現渲染問題。
對隱藏元素觸發的工具提示將不會運作。
對於 disabled 元素的工具提示必須在包裝元素中觸發。
當觸發來自於橫跨多行的超連結時，工具提示將會置中。在您的 <a>s，<b-link>s 和 <router-link>s 上使用 white-space: nowrap; 來避免此行為。
工具提示必須在對應的元素從 DOM 中移除之前隱藏。

定位

有十二個選項可供定位：top、topleft、topright、right、righttop、rightbottom、bottom、bottomleft、bottomright、left、lefttop 和 leftbottom 對齊。預設位置為 top。定位是相對於觸發元素。

動態範例

<div>
  <b-container fluid>
    <b-row class="text-center">
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.top="'Tooltip!'" variant="primary">Top</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.right="'Tooltip!'" variant="primary">Right</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.left="'Tooltip!'" variant="primary">Left</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.bottom="'Tooltip!'" variant="primary">Bottom</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.topright="'Tooltip!'" variant="primary">Top right</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.topleft="'Tooltip!'" variant="primary">Top left</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.bottomright="'Tooltip!'" variant="primary">Bottom right</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.bottomleft="'Tooltip!'" variant="primary">Bottom left</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.lefttop="'Tooltip!'" variant="primary">Left top</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.leftbottom="'Tooltip!'" variant="primary">Left bottom</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.righttop="'Tooltip!'" variant="primary">Right top</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.rightbottom="'Tooltip!'" variant="primary">Right bottom</b-button>
      </b-col>
    </b-row>
  </b-container>
</div>

<!-- b-tooltip-positioning.vue -->

觸發

工具提示可以使用下列任一組合觸發（開啟／關閉）：click、hover 和 focus。預設觸發為 hover focus。或者可以指定觸發為手動，此時彈出視窗僅能以程式化的方式開啟或關閉。

如果工具提示包含多個觸發，則所有觸發都必須清除後工具提示才會關閉。換言之，如果工具提示的觸發為 focus click，並且它是由 focus 開啟，而使用者之後按下觸發的元素，他們必須再按下一次並且將焦點移開才能關閉工具提示。

<div>
  <b-container>
    <b-row class="text-center">
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip="'Tooltip!'" variant="outline-success">Hover + Focus</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover="'Tooltip!'" variant="outline-success">Hover</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.click="'Tooltip!'" variant="outline-success">Click</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.focus="'Tooltip!'" variant="outline-success">Focus</b-button>
      </b-col>
    </b-row>
  </b-container>
</div>

<!-- b-tooltip-triggers.vue -->

讓工具提示也能用於鍵盤和輔助技術使用者

您僅應對傳統上可使用鍵盤操作且可互動的 HTML 元素添加工具提示（例如連結、按鈕或表單控制項）。儘管可以透過新增 tabindex="0" 屬性讓任意的 HTML 元素（例如 <span>s）具有焦點，但這可能會在非互動式元素上為鍵盤使用者新增可能會令人厭煩且混淆的定位標記。此外，大多數輔助技術目前並未在這種情況下宣布工具提示。

此外，請勿完全依賴 hover 作為提示觸發器，因為這會讓提示對僅使用鍵盤的使用者「不可能觸發」。

停用的元素

具備 disabled 屬性的元素沒有互動性，代表使用者無法集中注意力、將滑鼠游標懸停或按一下它們來觸發工具提示（或彈出視窗）。作為解決方法，您最好從包裝器 <div> 或 <span> 觸發提示，理想情況是讓它可以使用鍵盤集中注意力，方法是使用 tabindex="0"，並覆寫停用元素上的 pointer-events。

<div>
  <span class="d-inline-block" tabindex="0" v-b-tooltip.top title="Disabled tooltip">
    <b-button variant="primary" style="pointer-events: none;" disabled>Disabled button</b-button>
  </span>
</div>

<!-- disabled-trigger-element.vue -->

使用 `<button>` 元素的 `focus` 觸發器時會出現的注意事項

僅使用 focus 觸發器時，為了讓跨瀏覽器及跨平台行為正常，您必須使用讓出 <a> 標籤（而非 <button> 標籤）的元素，而且您還必須包含 tabindex="0" 屬性。

以下程式碼將產生看起來像按鈕的 <a>

<b-button
  href="#"
  tabindex="0"
  v-b-tooltip.focus
  title="Tooltip title"
>
  Link button with tooltip directive
</b-button>

在下次按一下時關閉

如果您想要一個只在按一下元素時才會開啟，但是當文件中的其他任一元件被按一下或獲得焦點時會關閉的工具提示，請同時使用 click 和 blur。

請注意，您的元素必須位於文件索引順序中，這個功能才有效。如果您的元素無法使用索引標籤，請將 tabindex="0" 屬性加入該元素。

標題內容

提供工具提示標題的選項有幾個。

預設情況下，工具提示會使用元素的 title 屬性作為工具提示內容。標題也可以物件的形式傳遞給 v-b-tooltip，其格式如下：

const options = {
  title: 'This is the title'
}

如果您的標題內容具備基本的 HTML 標記，您也需要將 html 屬性設定為 true，或使用指示符修改項 html

// Object format with HTML
const options = {
  title: 'This is the <strong>title</strong>',
  html: true
}

標題也可以是函式參照，每次開啟工具提示時都會呼叫該函式。如要在開啟時讓函式回傳的標題保持即時反應，請在內容變更時將標題設定為新的函式參照。

<template>
  <b-container>
    <b-row class="text-center">
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover :title="'Tip from title attribute ' + date" variant="success">Title</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover="'String Tip'" variant="success">String</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.html="tipData" variant="success">Data</b-button>
      </b-col>
      <b-col md="3" class="py-3">
        <b-button v-b-tooltip.hover.html="tipMethod" variant="success">Method</b-button>
      </b-col>
    </b-row>
  </b-container>
</template>

<script>
  export default {
    data() {
      return {
        tipData: { title: 'Tooltip <em>Message</em>' },
        date: new Date(),
        timer: null
      }
    },
    mounted() {
      this.timer = setInterval(() => {
        this.date = new Date()
      }, 1000)
    },
    beforeDestroy() {
      clearInterval(this.timer)
    },
    methods: {
      tipMethod() {
        // Note this is called each time the tooltip is first opened.
        return '<strong>' + new Date() + '</strong>'
      }
    }
  }
</script>

<!-- b-tooltip-content.vue -->

變體和自訂類別

BootstrapVue 的提示工具透過我們的自訂 CSS 支援情境色彩變異，使用指令變更器或組態選項

<template>
  <b-container fluid>
    <b-row class="text-center">
      <b-col>
        <b-button v-b-tooltip.hover.v-danger title="Danger variant">Danger Modifier</b-button>
      </b-col>
      <b-col>
        <b-button v-b-tooltip.hover="{ variant: 'info' }" title="Info variant">Info Config</b-button>
      </b-col>
    </b-row>
  </b-container>
</template>
<!-- b-tooltip-variants.vue -->

Bootstrap 預設主題變異為： danger、warning、success、primary、secondary、info、light，以及 dark。您可以透過 Bootstrap 的 SCSS 變數變更或新增額外的變異

可透過 customClass 選項屬性將自訂類別套用至提示工具外部包裝器 <div>

<b-button v-b-tooltip.hover="{ customClass: 'my-tooltip-class' }" title="Tooltip">Button</b-button>

指令語法和使用

<b-button v-b-tooltip:[container].[mod1].[mod2].[...].[modN]="<value>">Button</b-button>

其中 [container] 可以是（選用）

用於放置提示工具標記的元素 ID（不含 #）
若未提供，提示工具會附加在 body 中。如果觸發元素在對話框中，提示工具會附加在對話框的容器中

其中 [modX] 可以是（皆選用）

定位：top、bottom、left、right、auto、topleft、topright、bottomleft、bottomright、lefttop、leftbottom、righttop 或 rightbottom（找到最後一個，預設為 top）。
事件觸發：click、hover、focus、blur（未指定時，預設為 focus 和 hover。 blur 僅為關閉處理常式，且若自行指定，將轉換為 focus）。若您僅想要手動控制能見度，請使用 manual。
nofade 以關閉動畫。
html 以啟用呈現原始 HTML。HTML 預設為跳脫並轉換為文字。
格式為 d### 的延遲值（其中 ### 為 ms，預設為 50），套用至 hide 和 show。
顯示延遲值格式為 ds###（其中 ### 以毫秒為單位，預設為 50），僅套用於 show 觸發器。
顯示延遲值格式為 dh###（其中 ### 以毫秒為單位，預設為 50），僅套用於 hide 觸發器。
像素格式中的偏移值為 o###（其中 ### 為像素數，預設為 0，允許負值）。
邊界設定為 window 或 viewport。限制工具提示視覺位置的元素。如果未指定，則邊界預設為觸發元素的捲動父元素（在多數情況下，這就足夠了）。
內容變異形式為 v-XXX（其中 XXX 為顏色變異名稱）。
noninteractive 可讓工具提示與使用者無互動性。

其中 <value> 可為（選用）

包含工具提示標題的字串
產生工具提示標題的函數參考（接收一項自變數，為觸發工具提示的 DOM 元素參考）
包含工具提示更複雜組態的物件。詳見下方的可接受物件屬性

選項組態物件屬性

屬性	類型	預設值	說明
`動畫`	布林值	`true`	套用 CSS 顯示/隱藏過場到工具提示
`容器`	字串 ID 或 HTMLElement 或 `false`	`false`	將工具提示新增於特定元素。範例： `容器：'#body'`。此選項特別有用，讓您可在文件流程中靠近觸發元素的位置置放工具提示，這將可防止工具提示在調整視窗大小時從觸發元素飄走。設定為 `false` 時，工具提示將新增於 `body`，或如果觸發元素位於對話方塊內，將新增於對話方塊的容器
`延遲`	數字或物件	`50`	顯示和隱藏工具提示的延遲（毫秒）。如果提供數字，將延遲套用於隱藏/顯示。物件結構為： `延遲：{ "顯示": 500, "隱藏": 100 }`
`html`	布林值	`false`	於工具提示中允許 HTML。如果為 true，則工具提示中的 HTML 標籤將會呈現於工具提示中。如果為 false，則標題將插入為純文字。如果您擔心 XSS 攻擊，請使用文字
`位置`	字串或函式	`'top'`	工具提示的位置 - `auto`、`top`、`bottom`、`left`、`right`、`topleft`、`topright`、`bottomleft`、`bottomright`、`lefttop`、`leftbottom`、`righttop` 或 `rightbottom`。指定 `auto` 時，系統會動態調整工具提示方向
`標題`	字串或元素或函式	`''`	如果沒有標題屬性，預設標題值。如果提供函式，函式必須傳回一個字串
`觸發方式`	字串	`'hover focus'`	工具提示觸發方式：`click`、`hover`、`focus`。您可以傳遞多個觸發方式，請使用空格分隔觸發方式
`偏移`	數字或字串	`0`	相對於目標的工具提示偏移。如需詳細資訊，請參閱 Popper.js 的偏移文件
`備用位置`	字串或陣列	`'flip'`	允許您指定 Popper 在備用時會使用的位置。可以是 `flip`、`clockwise`、`counterclockwise` 或一陣列位置。如需詳細資訊，請參閱 Popper.js 的行為文件
`邊界`	字串 ID 或 HTMLElement	`'scrollParent'`	工具提示會在視覺上受到約束的容器。預設值在大部分情況下都已足夠，但如果您目標元素位於具有溢位捲動的小容器中，您可能需要變更此預設值。支援的值：`'scrollParent'` (預設值)、`'viewport'`、`'window'` 或 HTML 元素的參考
`邊界內距`	數字	`5`	用於定義邊界和工具提示之間最小距離的像素量。此設置可確保工具提示與容器邊緣之間始終保持一點內距
`互動性`	布林值	`true`	工具提示是否應具有使用者互動性
`變體`	字串	`null`	工具提示的背景顏色變體
`自訂類別`	字串	`null`	自訂類別名稱，套用於工具提示外層包裹元素
`ID`	字串	`null`	工具提示根元素使用的 ID。如果未提供 ID，系統會自動產生。如果您確實提供 ID，則保證只會在已顯示的頁面上顯示該 ID
`已停用`	布林值	`false`	設為 `true` 以停用工具提示

用法

最簡單的用法

v-b-tooltip="'This is a Tooltip!'"

或使用元素的 title 屬性作為工具提示內容

v-b-tooltip title="This is a title Tooltip"

位置範例

v-b-tooltip.bottom
v-b-tooltip.right

變體範例

v-b-tooltip.v-primary => `primary` variant
v-b-tooltip.v-danger => `danger` variant

觸發範例

v-b-tooltip.hover => Hover only
v-b-tooltip.click => Click only
v-b-tooltip.hover.focus => Both hover and focus

組合

v-b-tooltip.hover.bottom => Show on hover and place at bottom
v-b-tooltip.bottom.hover => Same as above
v-b-tooltip.bottom.hover.v-danger => Same as above, but with variant

物件

v-b-tooltip="{ title: 'Title', placement: 'bottom', variant: 'danger' }"

透過 $root 事件隱藏和顯示工具提示

你可以透過在 $root 中發出 bv::hide::tooltip 事件來關閉（隱藏）所有已開啟的工具提示

this.$root.$emit('bv::hide::tooltip')

如要關閉特定工具提示，請將觸發元素的 id 或工具提示的 id（如果在組態物件中提供）作為第一個參數傳遞

this.$root.$emit('bv::show::tooltip', 'my-trigger-button-id')

如要開啟特定工具提示，請將觸發元素的 id 或工具提示的 id（如果在組態物件中提供）作為第一個參數，在發出 bv::show::tooltip $root 事件時傳遞

this.$root.$emit('bv::show::tooltip', 'my-trigger-button-id')

如要同時開啟所有提示框，請在發出 bv::show::tooltip 事件時省略 id 參數。

這些事件適用於工具提示的元件和指令版本。

請注意，觸發元素必須存在於 DOM 中並處於可見狀態，以顯示工具提示。

透過 $root 事件停用和啟用工具提示

你可以透過在 $root 中發出 bv::disable::tooltip 事件來停用所有已開啟的工具提示

this.$root.$emit('bv::disable::tooltip')

如要停用特定工具提示，請將觸發元素的 id 或工具提示的 id（如果在組態物件中提供）作為第一個參數傳遞

this.$root.$emit('bv::disable::tooltip', 'my-trigger-button-id')

如要啟用特定工具提示，請將觸發元素的 id 或工具提示的 id（如果在組態物件中提供）作為第一個參數，在發出 bv::enable::tooltip $root 事件時傳遞

this.$root.$emit('bv::enable::tooltip', 'my-trigger-button-id')

如要同時啟用所有提示框，請在發出 bv::enable::tooltip 事件時省略 id 參數。

這些事件適用於工具提示的元件和指令版本。

請注意，觸發元素必須存在於 DOM 中，才能啟用或停用工具提示。

另請參閱

指令參考

匯入個別指令

你可以透過以下命名匯出，將個別指令匯入至你的專案

指令	命名匯出	匯入路徑
`v-b-tooltip`	`VBTooltip`	`bootstrap-vue`

範例

import { VBTooltip } from 'bootstrap-vue'
// Note: Vue automatically prefixes the directive name with 'v-'
Vue.directive('b-tooltip', VBTooltip)

作為 Vue.js 外掛導入

此外掛包含上方列出所有個別指令。

命名匯出	匯入路徑
`VBTooltipPlugin`	`bootstrap-vue`

範例

import { VBTooltipPlugin } from 'bootstrap-vue'
Vue.use(VBTooltipPlugin)

概述

定位

觸發