component or v-b-tooltip directive.">component or v-b-tooltip directive.">
报告问题编辑此页面

工具提示

通过 <b-tooltip> 组件或 v-b-tooltip 指令（首选方法）轻松地向元素或组件添加工具提示。

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

  <b-button id="tooltip-target-1">
    Hover Me
  </b-button>
  <b-tooltip target="tooltip-target-1" triggers="hover">
    I am tooltip <b>component</b> content!
  </b-tooltip>
</div>

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

概述

使用工具提示组件时需要注意的事项

  • 工具提示依赖于第三方库 Popper.js 进行定位。
  • 工具提示需要 BootstrapVue 的自定义 SCSS/CSS 才能正常运行，并适用于变体。
  • 在隐藏元素上触发工具提示将不起作用。
  • 将 container 指定为 null（默认，追加到 <body>）以避免在更复杂的组件（如输入组、按钮组等）中呈现问题。你可以使用 container 来选择性地指定一个不同的元素来附加呈现的工具提示。
  • 针对 disabled 元素的工具提示必须在包装元素上触发。
  • 当从跨多行的超链接触发时，工具提示将居中显示。在 <a>、<b-link> 和 <router-link> 上使用 white-space: nowrap; 来避免此行为。

目标

目标是将触发工具提示的触发器元素（或组件）。目标通过 target 属性指定，可以是以下任何一项

  • 标识触发器元素 ID（或组件根元素的 ID）的字符串
  • 对 HTMLElement 或 SVGElement 的引用（ref）（例如 this.$refs.refName）
  • 对组件的引用（ref），该组件的根元素是 HTMLElement 或 SVGElement（例如 this.$refs.refName）
  • 返回对 HTMLElement 或 SVGElement 的引用的函数（回调）

有关引用的更多信息，请参阅官方 Vue 文档。

注意

目标元素必须在 <b-tooltip> 挂载之前存在于文档中。如果在挂载期间找不到目标元素，则工具提示将永远不会打开。始终将 <b-tooltip> 组件放置在 DOM 中低于目标元素的位置。如果使用回调函数作为目标元素，此规则也适用，因为该回调仅在挂载时调用一次。

HTMLElement 指的是标准 HTML 元素，如 <div>、<button> 等，而 SVGElement 指的是 <svg> 或 SVG 支持的子元素。

定位

有十二种定位选项可用： top、topleft、topright、right、righttop、rightbottom、bottom、bottomleft、bottomright、left、lefttop 和 leftbottom 对齐。默认位置是 top。定位相对于触发元素。

有关定位的实际示例，请参阅 工具提示指令 文档。

触发器

可以通过 click、hover 和 focus 的任意组合来触发（打开/关闭）工具提示。默认触发器是 hover focus。或者可以指定 manual 触发器，其中弹出框只能通过 编程方式 打开或关闭。

如果工具提示有多个触发器，则必须清除所有触发器，工具提示才会关闭。即，如果工具提示具有触发器 focus click，并且它是由 focus 打开的，然后用户单击触发器元素，则他们必须再次单击它并移动焦点才能关闭工具提示。

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

<b-button id="link-button" href="#" tabindex="0">
  Link button with tooltip component
</b-button>
<b-tooltip target="link-button" title="Tooltip title" triggers="focus">
  Tooltip title
</b-tooltip>

让工具提示对键盘和辅助技术用户起作用

你应该只将工具提示添加到传统上可通过键盘聚焦且可交互的 HTML 元素（例如链接、按钮或表单控件）。虽然可以通过添加 tabindex="0" 属性使任意 HTML 元素（例如 <span>）可聚焦，但这会为键盘用户在非交互元素上添加可能令人讨厌且令人困惑的制表位。此外，大多数辅助技术目前不会在这种情况下宣布工具提示。

此外，不要仅仅依赖 hover 作为工具提示的触发器，因为这会使你的工具提示对于仅使用键盘的用户来说不可能触发。

已禁用元素

具有 disabled 属性的元素不可交互，这意味着用户无法聚焦、悬停或单击它们来触发工具提示（或弹出框）。作为一种解决方法，你将需要从包装器 <div> 或 <span> 触发工具提示，理想情况下使用 tabindex="0" 使其可通过键盘聚焦，并覆盖已禁用元素上的 pointer-events。

<div>
  <span id="disabled-wrapper" class="d-inline-block" tabindex="0">
    <b-button variant="primary" style="pointer-events: none;" disabled>Disabled button</b-button>
  </span>
  <b-tooltip target="disabled-wrapper">Disabled tooltip</b-tooltip>
</div>

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

<b-tooltip> 组件用法

<b-container fluid>
  <b-row>
    <b-col md="4" class="py-4">
      <b-button id="button-1" variant="outline-success">Live chat</b-button>
    </b-col>
    <b-col md="4" class="py-4">
      <b-button id="button-2" variant="outline-success">Html chat</b-button>
    </b-col>
    <b-col md="4" class="py-4">
      <b-button ref="button-3" variant="outline-success">Alternative chat</b-button>
    </b-col>
  </b-row>

  <!-- Tooltip title specified via prop title -->
  <b-tooltip target="button-1" title="Online!"></b-tooltip>

  <!-- HTML title specified via default slot -->
  <b-tooltip target="button-2" placement="bottom">
    Hello <strong>World!</strong>
  </b-tooltip>

  <!-- Tooltip for an element identified by ref -->
  <b-tooltip :target="() => $refs['button-3']" title="Alternative!"></b-tooltip>
</b-container>

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

组件选项

属性 默认值 说明 支持的值
target null 元素字符串 ID，或对元素或组件的引用，或返回其中任何一个的函数，你希望它触发工具提示 必需 任何有效的、文档中唯一的元素 ID、元素引用或组件引用，或返回任何此类 ID/引用的函数
title null 工具提示内容（仅文本，无 HTML）。如果需要 HTML，请将其放在默认插槽中 纯文本
placement 'top' 工具提示位置，相对于触发元素 top、bottom、left、right、auto、topleft、topright、bottomleft、bottomright、lefttop、leftbottom、righttop、rightbottom
fallback-placement “翻转” 工具提示的自动翻转放置行为，相对于触发元素 flip、clockwise、counterclockwise，或从左到右评估的有效放置位置数组
触发器 “悬停焦点” 事件的空间分隔列表，将触发工具提示的打开/关闭 hover、focus、click。请注意，blur 是一个特殊用例，用于在下次点击时关闭工具提示，通常与 click 结合使用。
不淡入淡出 false 设置为 true 时禁用淡入淡出动画 true 或 false
延迟 50 通过指定的毫秒数延迟显示和隐藏工具提示。还可以指定为 { show: 100, hide: 400 } 形式的对象，允许不同的显示和隐藏延迟 0 及以上，仅限整数。
偏移 0 将工具提示的中心移动指定的像素数 任何负整数或正整数
容器 null 元素字符串 ID，用于追加呈现的工具提示。如果 null 或未找到元素，则将工具提示追加到 <body>（默认） 任何有效的文档中唯一元素 ID。
边界 “scrollParent” 工具提示将在其中受到视觉约束的容器。在大多数情况下，默认值就足够了，但如果目标元素位于具有溢出滚动的较小容器中，则可能需要更改此值 'scrollParent'（默认）、'viewport'、'window'，或对 HTML 元素的引用。
边界填充 5 用于定义边界和工具提示之间最小距离的像素量。这可确保工具提示始终在其容器边缘之间留有一点填充 任何正数
非交互式 false 工具提示是否不应具有用户交互性 true 或 false
变体 null 工具提示的上下文颜色变体 任何上下文主题颜色变体名称
自定义类 null 应用于工具提示外部包装元素的自定义类名 字符串
ID null 在工具提示根元素上使用的 ID。如果没有提供，将自动生成一个。如果你确实提供了 ID，则必须保证在呈现的页面上是唯一的 有效的唯一元素 ID 字符串

非交互式工具提示

出于可访问性原因，BootstrapVue 的工具提示默认情况下具有用户交互性。要恢复 Bootstrap 的默认行为，请应用 noninteractive 道具

<div class="text-center">
  <div>
    <b-button id="tooltip-button-interactive">My tooltip is interactive</b-button>
    <b-tooltip target="tooltip-button-interactive">I will stay open when hovered</b-tooltip>
  </div>

  <div class="mt-3">
    <b-button id="tooltip-button-not-interactive">Mine is not...</b-button>
    <b-tooltip target="tooltip-button-not-interactive" noninteractive>Catch me if you can!</b-tooltip>
  </div>
</div>

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

变体和自定义类

BootstrapVue 的工具提示通过我们的自定义 CSS 支持上下文颜色变体，通过 variant 道具

<div class="text-center">
  <b-button id="tooltip-button-variant">Button</b-button>
  <b-tooltip target="tooltip-button-variant" variant="danger">Danger variant tooltip</b-tooltip>
</div>

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

Bootstrap 默认主题变体是：danger、warning、success、primary、secondary、info、light 和 dark。你可以通过 Bootstrap SCSS 变量 更改或添加其他变体

可以通过使用 custom-class 道具将自定义类应用于工具提示外部包装 <div>

<div class="text-center">
  <b-button id="my-button">Button</b-button>
  <b-tooltip target="my-button" custom-class="my-tooltip-class">Tooltip Title</b-tooltip>
</div>

variant 和 custom-class 是反应式的，可以在工具提示打开时更改。

请参阅 工具提示指令 文档，了解如何将变体和自定义类应用于指令版本。

以编程方式显示和隐藏工具提示

你可以通过可同步布尔值 show 道具手动控制工具提示的可见性。将其设置为 true 将显示工具提示，而将其设置为 false 将隐藏工具提示。

<template>
  <div class="text-center">
    <div>
      <b-button id="tooltip-button-1" variant="primary">I have a tooltip</b-button>
    </div>

    <div class="mt-3">
      <b-button @click="show = !show">Toggle Tooltip</b-button>
    </div>

    <b-tooltip :show.sync="show" target="tooltip-button-1" placement="top">
      Hello <strong>World!</strong>
    </b-tooltip>
  </div>
</template>
<script>
  export default {
    data: {
      show: true
    }
  }
</script>

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

要使工具提示在初始渲染时显示，只需在 <b-tooltip> 上添加 show 属性即可

<div class="text-center">
  <b-button id="tooltip-button-2" variant="primary">Button</b-button>
  <b-tooltip show target="tooltip-button-2">I start open</b-tooltip>
</div>

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

还可以通过通过引用向工具提示提交 'open' 和 'close' 事件来影响编程控制。

<template>
  <div class="d-flex flex-column text-md-center">
    <div class="p-2">
      <b-button id="tooltip-button-show-event" variant="primary">I have a tooltip</b-button>
    </div>

    <div class="p-2">
      <b-button class="px-1" @click="onOpen">Open</b-button>
      <b-button class="px-1" @click="onClose">Close</b-button>
    </div>

    <b-tooltip ref="tooltip" target="tooltip-button-show-event">
      Hello <strong>World!</strong>
    </b-tooltip>
  </div>
</template>

<script>
  export default {
    methods: {
      onOpen() {
        this.$refs.tooltip.$emit('open')
      },
      onClose() {
        this.$refs.tooltip.$emit('close')
      }
    }
  }
</script>

<!-- b-tooltip-show-ref-event.vue -->

您还可以使用 $root 事件来触发工具提示的显示和隐藏。有关详细信息，请参阅下面的通过 $root 事件隐藏和显示工具提示部分。

以编程方式禁用工具提示

您可以通过可同步布尔属性 disabled（默认为 false）禁用工具提示。将其设置为 true 将禁用工具提示。如果在将 disabled 设置为 false 时工具提示当前可见，则工具提示将保持可见，直到启用或以编程方式关闭它。如果通过 $root 事件禁用/启用工具提示（见下文），只要您提供了 .sync 属性修饰符，您的 disabled 值就会更新。

<template>
  <div class="d-flex flex-column text-md-center">
    <div class="p-2">
      <b-button id="tooltip-button-disable" variant="primary">I have a tooltip</b-button>
    </div>

    <div class="p-2">
      <b-button @click="disabled = !disabled">
        {{ disabled ? 'Enable' : 'Disable' }} Tooltip by prop
      </b-button>
      <b-button @click="disableByRef">
        {{ disabled ? 'Enable' : 'Disable' }} Tooltip by $ref event
      </b-button>

      <b-tooltip :disabled.sync="disabled" ref="tooltip" target="tooltip-button-disable">
        Hello <strong>World!</strong>
      </b-tooltip>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        disabled: false
      }
    },
    methods: {
      disableByRef() {
        if (this.disabled) {
          this.$refs.tooltip.$emit('enable')
        } else {
          this.$refs.tooltip.$emit('disable')
        }
      }
    }
  }
</script>

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

注意：在上述示例中，由于我们使用的是 focus hover 的默认工具提示触发器，因此工具提示会在禁用之前关闭，因为焦点（和悬停）已转移到切换按钮。

您还可以发出 $root 事件来触发禁用和启用工具提示。有关详细信息，请参阅下面的通过 $root 事件禁用和启用工具提示部分。

您还可以发出 $root 事件来触发禁用和启用弹出框。有关详细信息，请参阅下面的通过 $root 事件禁用和启用工具提示部分。

v-b-tooltip 指令用法

v-b-tooltip 指令使添加工具提示变得更加容易，无需额外的占位符标记

<b-container fluid>
  <b-row>
    <b-col md="6" class="py-4">
      <b-button v-b-tooltip title="Online!" variant="outline-success">Live chat</b-button>
    </b-col>

    <b-col md="6" class="py-4">
      <b-button
        v-b-tooltip.html
        title="Hello <strong>World!</strong>"
        variant="outline-success"
      >
        Html chat
      </b-button>
    </b-col>
  </b-row>
</b-container>

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

有关指令格式的更多信息和功能，请参阅 v-b-tooltip 文档。

“全局”$root 实例事件

使用 $root 实例，可以在组件外部的某个位置触发和监听事件，其中使用了 <b-collapse>。简而言之，$root 的行为类似于全局事件触发器和监听器。有关 $root 实例的详细信息，请参阅 官方 Vue 文档。

通过 $root 事件隐藏和显示工具提示

你可以通过在 $root 上触发 bv::hide::tooltip 事件来关闭（隐藏）所有打开的工具提示

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

若要关闭特定工具提示，请传递触发元素的 id 或工具提示的 id（如果通过 id prop 提供了该 id）作为参数

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

若要打开特定工具提示，请传递触发元素的 id 或工具提示的 id（如果通过 id prop 提供了该 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（如果通过 id prop 提供了该 id）作为参数

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

要启用特定工具提示，请传递触发元素的 id，或工具提示的 id（如果通过 id 属性提供），作为发出 bv::enable::tooltip $root 事件时的参数

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

要同时启用所有工具提示，请在发出 bv::enable::tooltip 事件时省略 id 参数。

这些事件适用于工具提示的组件和指令版本。

注意：触发元素必须存在于 DOM 中，才能启用或禁用工具提示。

通过 $root 事件侦听工具提示更改

要侦听任何工具提示的打开，请使用

export default {
  mounted() {
    this.$root.$on('bv::tooltip::show', bvEvent => {
      console.log('bvEvent:', bvEvent)
    })
  }
}

有关事件的完整列表，请参阅文档的 事件 部分。

辅助功能

当工具提示显示时，触发元素将具有属性 aria-describedby，并设置工具提示的自动生成 ID。

注意：此组件的动画效果取决于 prefers-reduced-motion 媒体查询。有关更多详细信息，请参阅 辅助功能文档的减少运动部分。

组件参考

<b-tooltip>

查看源代码

属性

所有属性默认值均可 全局配置。

属性
(单击以升序排序)
类型
(单击以升序排序)
默认值
说明
边界
HTMLElement 或 Object 或 String“scrollParent”工具提示的边界约束：'scrollParent'、'window'、'viewport'，或对 HTMLElement 或组件的引用
边界填充
Number 或 String50工具提示将尝试远离边界元素边缘，像素数由具体值指定
容器
HTMLElement 或 Object 或 String当可见时，附加呈现的工具提示的容器元素。默认为 body 元素
自定义类
字符串应用于工具提示根元素的 CSS 类（或类）
延迟
Number 或 Object 或 String50显示和隐藏延迟的值。当指定为数字或字符串时，适用于显示和隐藏。使用对象形式分别设置显示和隐藏延迟
disabled
布尔值false设置为 `true` 时，禁用组件的功能并使其处于禁用状态
fallback-placement
Array 或 String“翻转”工具提示超出边界时使用的放置。有关更多详细信息，请参阅文档
ID
字符串用于设置呈现内容上的 `id` 属性，并用作根据需要生成任何其他元素 ID 的基础
不淡入淡出
布尔值false设置为 `true` 时，禁用组件上的淡入淡出动画/过渡
非交互式
v2.2.0+ 		布尔值false工具提示是否不应具有用户交互性
偏移
Number 或 String0与触发目标元素相比，箭头中心的偏移量（以像素为单位）
placement
字符串'top'工具提示的放置：'top'、'bottom'、'right'、'left'、'topleft'、'topright'、'bottomleft'、'bottomright'、'lefttop'、'leftbottom'、'righttop'、'rightbottom' 之一
show
布尔值false设置后将显示工具提示
target
必需 		HTMLElement 或 SVGElement 或 Function 或 Object 或 String元素字符串 ID，或对要触发工具提示的元素或组件的引用
title
字符串要放置在工具提示中的文本
触发器
Array 或 String“悬停焦点”指定哪些触发器将显示工具提示。支持的值为 'click'、'hover'、'focus'。有关特殊触发器 'blur' 和 'manual'，请参阅文档
变体
字符串将 Bootstrap 主题颜色变体之一应用于组件

插槽

名称
说明
default 工具提示内容的插槽（支持 HTML/组件）

事件

事件
(单击以升序排序)
参数
说明
bv::tooltip::disabled
  1. bvEvent - BvEvent 对象
当工具提示变为禁用时在 $root 上触发
bv::tooltip::enabled
  1. bvEvent - BvEvent 对象
当工具提示变为启用时在 $root 上触发
bv::tooltip::hidden
  1. bvEvent - BvEvent 对象
当工具提示隐藏时在 $root 上触发
bv::tooltip::hide
  1. bvEvent - BvEvent 对象。可取消
当工具提示即将隐藏时在 $root 上触发。可取消。调用 bvEvent.preventDefault() 取消隐藏
bv::tooltip::show
  1. bvEvent - BvEvent 对象。可取消
当工具提示即将显示时在 $root 上触发。可取消。调用 bvEvent.preventDefault() 取消显示
bv::tooltip::shown
  1. bvEvent - BvEvent 对象
当工具提示显示时在 $root 上触发
disabled
  1. bvEvent - BvEvent 对象
当工具提示变为禁用时触发
enabled
  1. bvEvent - BvEvent 对象
当工具提示变为启用时触发
hidden
  1. bvEvent - BvEvent 对象
当工具提示隐藏时触发
hide
  1. bvEvent - BvEvent 对象。可取消
当工具提示即将隐藏时触发。可取消。调用 bvEvent.preventDefault() 取消隐藏
show
  1. bvEvent - BvEvent 对象。可取消
当工具提示即将显示时触发。可取消。调用 bvEvent.preventDefault() 取消显示
shown
  1. bvEvent - BvEvent 对象
当工具提示显示时触发

$root 事件侦听器

你可以通过在 $root 上触发以下事件来控制 <b-tooltip>

事件
参数
说明
bv::disable::tooltip

id - 要禁用的工具提示 ID（可选）

当此事件在 $root 上触发时禁用所有或特定工具提示
bv::enable::tooltip

id - 要启用的工具提示 ID（可选）

当此事件在 $root 上触发时启用所有或特定工具提示
bv::hide::tooltip

id - 要隐藏的工具提示 ID（可选）

当此事件在 $root 上触发时关闭（隐藏）所有或特定打开的工具提示
bv::show::tooltip

id - 要显示的工具提示 ID（可选）

当此事件在 $root 上触发时打开（显示）所有或特定工具提示

导入单个组件

你可以通过以下命名导出项将各个组件导入到你的项目中

组件
命名导出
导入路径
<b-tooltip>BTooltipbootstrap-vue

示例

import { BTooltip } from 'bootstrap-vue'
Vue.component('b-tooltip', BTooltip)

作为 Vue.js 插件导入

此插件包含上面列出的所有各个组件。插件还包括任何组件别名。

命名导出
导入路径
TooltipPluginbootstrap-vue

此插件还自动包含以下插件

  • VBTooltipPlugin

示例

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