工具提示 | 指令 | 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>、<b-link> 和 <router-link> 上使用 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>）可聚焦，但这会为键盘用户在非交互元素上添加可能令人讨厌且令人困惑的制表位。此外，大多数辅助技术目前不会在此情况下播报工具提示。

此外，不要仅仅依赖 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### 的延迟值（其中 ### 以毫秒为单位，默认为 50），应用于 hide 和 show。
以 ds### 格式表示的显示延迟值（其中 ### 以毫秒为单位，默认为 50），仅应用于 show 触发器。
以 dh### 格式表示的隐藏延迟值（其中 ### 以毫秒为单位，默认为 50），仅应用于 hide 触发器。
以 o### 格式表示的像素偏移值（其中 ### 为像素数，默认为 0。允许负值）。
边界设置为 window 或 viewport。用于限制工具提示的可视位置的元素。如果未指定，则边界默认为触发元素的滚动父级（在大多数情况下，这已足够）。
以 v-XXX 形式表示的上下文变体（其中 XXX 为颜色变体名称）。
noninteractive 使工具提示不具有用户交互性。

其中 <value> 可以是（可选）

包含工具提示标题的字符串
生成工具提示标题的函数引用（接收一个参数，该参数是对触发工具提示的 DOM 元素的引用）
包含工具提示更复杂配置的对象。有关可接受的对象属性，请参见下文

选项配置对象属性

属性	类型	默认值	说明
`animation`	布尔值	`true`	对工具提示应用 CSS 淡入淡出过渡
`container`	字符串 ID 或 HTMLElement 或 `false`	`false`	将工具提示附加到特定元素。示例：`container: '#body'`。此选项特别有用，因为它允许您将工具提示定位在触发元素附近的文档流中 - 这将防止工具提示在窗口调整大小期间远离触发元素。当设置为 `false` 时，工具提示将附加到 `body`，或者如果触发元素位于模态框中，它将附加到模态框的容器
`delay`	数字或对象	`50`	延迟显示和隐藏工具提示（毫秒）。如果提供数字，则延迟应用于隐藏/显示。对象结构为：`delay: { "show": 500, "hide": 100 }`
`html`	布尔值	`false`	允许在工具提示中使用 HTML。如果为 true，则工具提示标题中的 HTML 标记将在工具提示中呈现。如果为 false，则标题将作为纯文本插入。如果您担心 XSS 攻击，请使用文本
`placement`	字符串或函数	`'top'`	如何定位工具提示 - `auto`、`top`、`bottom`、`left`、`right`、`topleft`、`topright`、`bottomleft`、`bottomright`、`lefttop`、`leftbottom`、`righttop` 或 `rightbottom`。当指定 `auto` 时，它会动态重新调整工具提示的方向
`title`	字符串或元素或函数	`''`	如果 title 属性不存在，则为默认标题值。如果给定函数，则它必须返回一个字符串
`trigger`	字符串	`'hover focus'`	工具提示的触发方式：`click`、`hover`、`focus`。你可以传递多个触发器；用空格分隔它们
`offset`	数字或字符串	`0`	工具提示相对于其目标的偏移量。有关更多信息，请参阅 Popper.js 的偏移量文档
`fallbackPlacement`	字符串或数组	`'flip'`	允许指定 Popper 在后备时将使用哪个位置。可以是 `flip`、`clockwise`、`counterclockwise` 或一个位置数组。有关更多信息，请参阅 Popper.js 的行为文档
`boundary`	字符串 ID 或 HTMLElement	`'scrollParent'`	工具提示在视觉上受到限制的容器。在大多数情况下，默认值就足够了，但如果你的目标元素在一个带有溢出滚动的较小容器中，则可能需要更改此值。支持的值：`'scrollParent'`（默认值）、`'viewport'`、`'window'` 或对 HTML 元素的引用
`boundaryPadding`	数字	`5`	用于定义边界和工具提示之间的最小距离的像素量。这确保工具提示始终在其容器边缘之间留有一些填充
`interactive`	布尔值	`true`	工具提示是否应具有用户交互性
`variant`	字符串	`null`	工具提示的上下文颜色变体
`customClass`	字符串	`null`	要应用于工具提示外部包装器元素的自定义类名
`id`	字符串	`null`	用于工具提示根元素的 ID。如果没有提供，则会自动生成一个。如果你确实提供了 ID，则必须保证它在呈现的页面上是唯一的
`disabled`	布尔值	`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（如果在配置对象中提供了该 id）作为第一个参数传递

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

要打开一个特定工具提示，请在触发 bv::show::tooltip $root 事件时，将触发元素的 id 或工具提示的 id（如果在配置对象中提供了该 id）作为第一个参数传递

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）作为第一个参数传递

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

要启用一个特定工具提示，请在触发 bv::enable::tooltip $root 事件时，将触发元素的 id 或工具提示的 id（如果在配置对象中提供了该 id）作为第一个参数传递

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)

概述

定位

触发器