tip提示组件(Tooltip)

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

总览

使用工具提示组件时要了解的事项:

  • 工具提示依赖于第三方库Popper.js 进行定位.
  • 工具提示需要BootstrapVue的自定义SCSS / CSS才能正常运行,并提供变体.
  • 在隐藏元素上触发工具提示将不起作用.
  • container 指定为 null (默认值, 追加到 <body>) 以避免在更复杂的组件(如输入组, 按钮组等)中出现渲染问题. 您可以使用容器来选择指定其他元素,以将呈现的工具提示附加到该元素.
  • 禁用 元素 的工具提示必须在包装器元素上触发.
  • 从跨越多行的超链接触发时,工具提示将居中。 使用空格: nowrap; 在您的 <a>s, <b-link>s 和 <router-link>上,以避免行为.
<b-tooltip> 目标元素必须存在于文档中.

如果在安装过程中未找到目标元素, 则工具提示将永远不会打开.始终将<b-tooltip> 组件放置在DOM中低于目标元素的位置. 如果将回调用作目标元素,则该规则也适用,因为该回调在装入时仅被调用一次.

定位

十二个选项可用于定位: 顶部左上右上右上右下底部左下右下左上左下 对齐. 默认位置 top. 位置相对于触发元素.

触 发

可以通过 单机 , 悬停焦点的任意组合来触发(打开/关闭)工具提示. 默认触发器是悬停 焦点. 或者可以指定一个 手动 触发器, 其中只能以编程方式打开或关闭弹窗.

如果工具提示包含多个触发器, 则必须先清除所有触发器,然后工具提示才会关闭. 即 如果工具提示单击了触发 焦点, 并且被焦点 打开, 然后用户单击了触发元素, 则他们必须 再次 单击并移动焦点以关闭工具提示.

重点 触发 <button> 元素的警告

为了使用 焦点 触发器时正确的跨浏览器和跨平台行为, 必须使用呈现<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元素(如链接,按钮或表单控件)添加工具提示. 能使任意HTML元素 (例如<span>s) 成为可聚焦的, 虽然可以通过添加 tabindex="0" 来操作, 但这将为键盘用户在非交互式元素上添加潜在的令人讨厌且令人困惑的制表位. 此外, 在这种情况下,目前大多数辅助技术都不会公布工具提示.

此外, 不要仅将悬停作为工具提示的 触发器 , 因为这将使仅键盘用户 无法触发工具提示.

禁用元素

具有禁用 属性的 不是交互式的, 这意味着用户无法聚焦, 悬停或单击它们来触发工具提示 (或弹出窗口). 解决方法是, 您要通过包装 <div><span>触发工具提示, 最好使用 tabindex="0"将其设置为键盘焦点, 并覆盖禁用 禁用元素 上的指针事件.

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

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

组件选项

道具 默认 描述 支持值
目标 空值 要触发工具提示的元素字符串 ID, 或对元素或组件的引用, 或返回其中任何一个的 函数 任何有效的,文档中唯一元素 ID, 元素引用或组件引用, 或者返回任何 此类 ID / 引用的函数
标题 空值 工具提示内容 (仅文本, 无 HTML). 如需要 HTML 请将其放在默认位置/td> 纯文本
放置 '上' 相对于触发元素的工具提示位置 , , , , 自动, 左上, 右上, 左下, 右下, 左上, 左下, 右上, 右下
后备位置 '翻转' 工具提示相对于触发元素的自动翻转放置行为 翻转, 顺时针, 逆时针e 或从左到右评估的有效展示位置数组
触发器 '悬停焦点' 用空格分隔的事件列表,将触发工具提示的打开/关闭 鼠标悬停在焦点上, 然后 单击. 注意 模糊 是一种特殊的用例, 用于下次 单击时关闭工具提示,通常与单击结合使用.
不褪色 虚假 设置为true时禁用淡入淡出动画
延迟 50 将工具提示的显示和隐藏延迟指定的毫秒数. 也可以指定为 { show: 100, hide: 400 }形式的对象,从而允许不同的显示和隐藏延迟 0 及以上, 及整数.
抵销 0 将工具提示的中心按指定像素数移动 任何负或正整数
容器 空值 元素字符串 ID,用于将呈现的工具提示附加到其中. 如果为 null 或未找到元素, 则将工具提示附加到 <body> (默认) 任何有效的文档内唯一元素 ID.
边界 'scrollParent' 工具提示将在视觉上受到约束的容器. 在大多数情况下, 默认值就足够了,但是如果目标元素位于带有溢出滚动条的小容器中,则可能需要更改此设置 'scrollParent' (默认), '视口', '窗口', 或对 HTML 元素的引用.
边界填充 5 用于定义边界和工具提示之间的最小距离的像素数量. 这样可以确保工具提示在其容器的边缘之间始终有少许填充物 任何正数
非互动 工具提示是否不应与用户互动
变体 空值 工具提示的上下文颜色变体 任何上下文主题颜色变体名称
制定类 空值 应用于工具提示外部包装器元素的自定义类名 一串
id 空值 在工具提示根元素上使用的ID. 如果没有提供,将自动生成一个. 如果确实提供ID, 则 必须 确保该ID在呈现的页面上是唯一的 有效的唯一元素ID字符串

非交互式工具提示

出于辅助功能的考虑,Bootstraps工具提示默认情况下是用户交互的. 要恢复引导程序的默认行为,请应用 非交互式 道具:

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

变体和自定义类

BootstrapVue's 的工具提示通过我们的自定义 CSS, 和 变体 prop支持上下文颜色变体:

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

Bootstrap default theme variants are: danger, warning, success, primary, secondary, info, light, and dark. You can change or add additional variants via Bootstrap SCSS variables

A custom class can be applied to the tooltip outer wrapper <div> by using the custom-class prop:

<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 and custom-class are reactive and can be changed while the tooltip is open.

Refer to the tooltip directive docs on applying variants and custom class to the directive version.

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

Y您可以通过可同步的布尔值显示道具手动控制工具 提示的 可见性. 将其设置为 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>

要使工具提示显示在初始渲染中, 只需把 show道具 添加在 <b-tooltip>上:

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

通过引用将 '打开''关闭' 事件提交给工具提示, 也可以影响程序控制.

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

您还可以使用 $root 事件触发工具提示的显示和隐藏. 有关 详细信息, and showing tooltips via $root events section below for details.

以编程方式禁用工具提示

您可以通过可禁用的 Boolean属性 禁用 工具提示 (默认为 false) 将其设置为 true 将禁用工具提示. 如果禁用时当前将工具提示设置为 false, 则工具提示将保持可见,直到启用或以编程方式将其关闭. 如果 通过$ root事件禁用/启用了工具提示 (请参见下文), 则只要 提供了 .sync prop修饰符, 您的禁用值就会更新.

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

注意: 在上面的示例中, 由于我们使用的是焦点悬停的默认工具提示 触发器, 由于工具栏上的焦点丢失(并悬停了),该工具提示在被禁用之前将关闭.

您还可以发出 $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>

有关指令格式的更多信息和功能,请参考 v-b-tooltip 文档 features of the directive format.

'全局' $ root 事件

使用 $root 实例可以在使用 <b-collapse> 的组件之外的某个地方发出和监听事件. 简而言之, $root 的行为类似于全局事件的发射器和侦听器. 有关 $root 实例的详细信息可以在 Vue 官方文档中找到.

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

You can close (hide) all open tooltips by emitting the bv::hide::tooltip event on $root:

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

To close a specific tooltip, pass the trigger element's id, or the id of the tooltip (if one was provided via the id prop), as the argument:

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

To open a specific tooltip, pass the trigger element's id, or the id of the tooltip (if one was provided via the id prop), as the argument when emitting the bv::show::tooltip $root event:

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

To open all tooltips simultaneously, omit the id argument when emitting the bv::show::tooltip event.

These events work for both the component and directive versions of tooltip.

Note: the trigger element must exist in the DOM and be in a visible state in order for the tooltip to show.

通过$ root事件禁用和启用工具提示

You can disable all open tooltips by emitting the bv::disable::tooltip event on $root:

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

To disable a specific tooltip, pass the trigger element's id, or the id of the tooltip (if one was provided via the id prop), as the argument:

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

To enable a specific tooltip, pass the trigger element's id, or the id of the tooltip (if one was provided via the id prop), as the argument when emitting the bv::enable::tooltip $root event:

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

To enable all tooltips simultaneously, omit the id argument when emitting the bv::enable::tooltip event.

These events work for both the component and directive versions of tooltip.

Note: The trigger element must exist in the DOM in order for the tooltip to be enabled or disabled.

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

To listen to any tooltip opening, use:

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

有关事件的完整列表 请参阅文档的“事件”部分.

组件参考

<b-tooltip>

所有产物

属性 (Click to sort Ascending) 类型 默认 描述
title String Text to place in the tooltip
target Required String or HTMLElement or SVGElement or Function or Object Element string ID, or a reference to an element or component, that you want to trigger the tooltip.
triggers String or Array 'hover focus' Specify which triggers will show the tooltip. Supported values are 'click', 'hover', 'focus'. Refer to the docs for special triggers 'blur' and 'manual'
placement String 'top' Placement of the tooltip: One of 'top', 'bottom', 'right', 'left', 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'left-top', 'left-bottom', 'right-top', 'right-bottom'
fallback-placement String or Array 'flip' placement to use when the tooltip would be out of boundaries. Refer to the docs for more details
variant String Applies one of the Bootstrap theme color variants to the component
custom-class String CSS class (or classes) to apply to the tooltip's root element
delay Number or Object or String 50 Value for the show and hide delay. Applies to both show and hide when specified as a number or string. Use object form to set show and hide delays individually
boundary String or HTMLElement or Object 'scrollParent' The boundary constraint of the tooltip: 'scrollParent', 'window', 'viewport', or a reference to an HTMLElement or component
boundary-padding Number or String 5 The tooltip will try and stay away from the edge of the boundary element by the number of pixels specificed
offset Number or String 0 Offset (in pixels) for the arrow center compared to the trigger target element
no-fade Boolean false When set to 'true', disables the fade animation/transition on the component
container String or HTMLElement or Object The container element to append the rendered tooltip when visible. Default's to the body element
show Boolean false When set will show the tooltip
noninteractive v2.2.0+ Boolean false Wether the tooltip should not be user-interactive
disabled Boolean false 设置为“true”时,禁用组件的功能并将其置于禁用状态
id String 用于在渲染的内容上设置“id”属性,并用作根据需要生成任何其他元素ID的基础

插槽

插槽名称 描述
default Slot for tooltip content (HTML/components supported)

事件列表

事件 参数 描述
show
  1. bvEvent - bvEvent object. Cancelable.
Emitted when tooltip is about to be shown. Cancelable. Call bvEvent.preventDefault() to cancel show.
shown
  1. bvEvent - bvEvent object.
Emitted when tooltip is shown
hide
  1. bvEvent - bvEvent object. Cancelable.
Emitted when tooltip is about to be hidden. Cancelable. Call bvEvent.preventDefault() to cancel hide.
hidden
  1. bvEvent - bvEvent object.
Emitted when tooltip is hidden
enabled
  1. bvEvent - bvEvent object
Emitted when tooltip becomes enabled
disabled
  1. bvEvent - bvEvent object
Emitted when tooltip becomes disabled
bv::tooltip::show
  1. bvEvent - bvEvent object. Cancelable.
Emitted on $root when tooltip is about to be shown. Cancelable. Call bvEvent.preventDefault() to cancel show.
bv::tooltip::shown
  1. bvEvent - bvEvent object.
Emitted on $root when tooltip is shown
bv::tooltip::hide
  1. bvEvent - bvEvent object. Cancelable.
Emitted on $root when tooltip is about to be hidden. Cancelable. Call bvEvent.preventDefault() to cancel hide.
bv::tooltip::hidden
  1. bvEvent - bvEvent object.
Emitted on $root when tooltip is hidden
bv::tooltip::enabled
  1. bvEvent - bvEvent object.
Emitted on $root when tooltip becomes enabled
bv::tooltip::disabled
  1. bvEvent - bvEvent object.
Emitted on $root when tooltip becomes disabled

$root事件监听器

控制 <b-tooltip> 可以通过 在 $root上发出以下事件:

事件 参数 描述
bv::hide::tooltip

id - (optional), tooltip id to hide

Close (hide) all or a specific open tooltip when this event is emitted on $root
bv::show::tooltip

id - (optional), tooltip id to show

Open (show) all or a specific tooltip when this event is emitted on $root
bv::disable::tooltip

id - (optional), tooltip id to disable

Disable all or a specific tooltip when this event is emitted on $root
bv::enable::tooltip

id - (optional), tooltip id to enable

Enable all or a specific tooltip when this event is emitted on $root

导入单个组件

您可以通过以下命名的导出将单个组件导入到项目中:

组件 命名输出 导入路径
<b-tooltip> BTooltip bootstrap-vue

示例:

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

导入为Vue.js 插件

该插件包括上面列出的所有单个组件。插件还包括任何组件别名。

命名输出 导入路径
TooltipPlugin bootstrap-vue

该插件还自动包括以下插件:

  • VBTooltipPlugin

例:

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