in English

工具提示

使用 CSS3 动画和 data-bs-attributes 本地标题存储的 CSS 和 JavaScript 添加自定义引导工具提示的文档和示例。

在本页面

概述

使用工具提示插件时要知道的事情：

工具提示依赖 3rd 方库Popper进行定位。您必须在 bootstrap.js 之前包含popper.min.js或使用包含 Popper 的bootstrap.bundle.min.js/以使工具提示起作用！bootstrap.bundle.js
出于性能原因，工具提示是可选的，因此您必须自己初始化它们。
从不显示具有零长度标题的工具提示。
指定container: 'body'以避免在更复杂的组件（如我们的输入组、按钮组等）中出现渲染问题。
在隐藏元素上触发工具提示将不起作用。
.disabled或元素的工具提示disabled必须在包装元素上触发。
当从跨越多行的超链接触发时，工具提示将居中。white-space: nowrap;在你的 s 上使用<a>以避免这种行为。
在从 DOM 中删除相应元素之前，必须隐藏工具提示。
由于影子 DOM 中的元素，可以触发工具提示。

默认情况下，该组件使用内置的内容清理器，它会去除任何未明确允许的 HTML 元素。有关更多详细信息，请参阅我们的 JavaScript 文档中的 sanitizer 部分。

该组件的动画效果依赖于 prefers-reduced-motion媒体查询。请参阅我们可访问性文档的减少运动部分。

明白了吗？太好了，让我们通过一些示例来看看它们是如何工作的。

示例：随处启用工具提示

初始化页面上所有工具提示的一种方法是通过它们的data-bs-toggle属性来选择它们：

var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new bootstrap.Tooltip(tooltipTriggerEl)
})

例子

将鼠标悬停在下面的链接上以查看工具提示：

将鼠标悬停在下面的按钮上可查看四个工具提示方向：顶部、右侧、底部和左侧。在 RTL 中使用 Bootstrap 时会镜像方向。

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Tooltip on top">
  Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="Tooltip on right">
  Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Tooltip on bottom">
  Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" title="Tooltip on left">
  Tooltip on left
</button>

并添加了自定义 HTML：

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

使用 SVG：

萨斯

变量

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     $white;
$tooltip-bg:                        $black;
$tooltip-border-radius:             $border-radius;
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer * .25;
$tooltip-padding-x:                 $spacer * .5;
$tooltip-margin:                    0;

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
$tooltip-arrow-color:               $tooltip-bg;

用法

工具提示插件按需生成内容和标记，默认情况下将工具提示放置在其触发元素之后。

通过 JavaScript 触发工具提示：

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)

溢出`auto`和`scroll`

当父容器有overflow: auto或overflow: scroll喜欢我们的时，工具提示位置会尝试自动更改.table-responsive，但仍保持原始位置的定位。要解决此问题，请将boundary选项（使用popperConfig选项的翻转修饰符）设置为任何 HTMLElement 以覆盖默认值'clippingParents'，例如document.body：

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
  boundary: document.body // or document.querySelector('#boundary')
})

标记

工具提示所需的标记只是一个data属性，并且title在您希望拥有工具提示的 HTML 元素上。生成的工具提示标记相当简单，尽管它确实需要一个位置（默认情况下，top由插件设置）。

使工具提示适用于键盘和辅助技术用户

您应该只将工具提示添加到传统上可通过键盘聚焦和交互的 HTML 元素（例如链接或表单控件）。尽管可以通过添加属性使任意 HTML 元素（例如<span>s）成为焦点tabindex="0"，但这会为键盘用户在非交互式元素上添加可能令人讨厌和令人困惑的制表位，并且目前大多数辅助技术不会在这种情况下公布工具提示。此外，不要仅仅依靠hover作为工具提示的触发器，因为这会使键盘用户无法触发工具提示。

<!-- HTML to write -->
<a href="#" data-bs-toggle="tooltip" title="Some tooltip text!">Hover over me</a>

<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-top" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

禁用元素

具有该disabled属性的元素不是交互式的，这意味着用户无法聚焦、悬停或单击它们来触发工具提示（或弹出框）。作为一种解决方法，您需要从包装器中触发工具提示，<div>或者<span>理想情况下使用tabindex="0".

<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" title="Disabled tooltip">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

选项

选项可以通过数据属性或 JavaScript 传递。对于数据属性，将选项名称附加到中data-bs-，如data-bs-animation="". 通过数据属性传递选项时，请确保将选项名称的大小写类型从 camelCase 更改为 kebab-case。例如，不要使用，而是data-bs-customClass="beautifier"使用data-bs-custom-class="beautifier"。

请注意，出于安全原因 sanitize，不能使用数据属性提供 sanitizeFn、和选项。allowList

姓名	类型	默认	描述
`animation`	布尔值	`true`	对工具提示应用 CSS 淡入淡出过渡
`container`	字符串 \| 元素 \| 错误的	`false`	将工具提示附加到特定元素。示例：`container: 'body'`。此选项特别有用，因为它允许您将工具提示定位在文档流中靠近触发元素的位置 - 这将防止工具提示在窗口调整大小期间从触发元素浮动。
`delay`	号码 \| 目的	`0`	延迟显示和隐藏工具提示 (ms) - 不适用于手动触发类型如果提供了一个数字，延迟将应用于隐藏/显示对象结构为：`delay: { "show": 500, "hide": 100 }`
`html`	布尔值	`false`	在工具提示中允许 HTML。如果为 true，则工具提示中的 HTML 标记`title`将在工具提示中呈现。如果为 false，`innerText`属性将用于将内容插入 DOM。如果您担心 XSS 攻击，请使用文本。
`placement`	字符串 \| 功能	`'top'`	如何定位工具提示 - 自动 \| 顶部 \| 底部 \| 离开 \| 正确的。指定时`auto`，它将动态地重新定向工具提示。当一个函数用于确定位置时，它会以工具提示 DOM 节点作为其第一个参数，触发元素 DOM 节点作为其第二个参数来调用。`this`上下文设置为工具提示实例。
`selector`	字符串 \| 错误的	`false`	如果提供了选择器，则工具提示对象将被委托给指定的目标。在实践中，这也用于将工具提示应用于动态添加的 DOM 元素（`jQuery.on`支持）。请参阅this和一个内容丰富的示例。
`template`	细绳	`'<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'`	创建工具提示时要使用的基本 HTML。工具提示`title`将被注入到`.tooltip-inner`. `.tooltip-arrow`将成为工具提示的箭头。最外层的包装元素应该有`.tooltip`类和`role="tooltip"`.
`title`	字符串 \| 元素 \| 功能	`''`	`title`如果属性不存在，则默认标题值。如果给定了一个函数，它将被调用，并将其`this`引用设置为工具提示附加到的元素。
`trigger`	细绳	`'hover focus'`	工具提示是如何触发的 - 点击 \| 悬停 \| 焦点 \| 手动的。您可以传递多个触发器；用空格分隔它们。 `'manual'`指示工具提示将通过`.show()`,`.hide()`和`.toggle()`方法以编程方式触发；此值不能与任何其他触发器组合。 `'hover'`其本身将导致无法通过键盘触发的工具提示，并且仅应在存在为键盘用户传达相同信息的替代方法时使用。
`fallbackPlacements`	大批	`['top', 'right', 'bottom', 'left']`	通过提供数组中的展示位置列表（按优先顺序）来定义后备展示位置。有关更多信息，请参阅 Popper 的行为文档
`boundary`	字符串 \| 元素	`'clippingParents'`	工具提示的溢出约束边界（仅适用于 Popper 的 preventOverflow 修饰符）。默认情况下，它`'clippingParents'`可以接受 HTMLElement 引用（仅通过 JavaScript）。有关更多信息，请参阅 Popper 的detectOverflow 文档。
`customClass`	字符串 \| 功能	`''`	显示时将类添加到工具提示。请注意，除了模板中指定的任何类之外，还将添加这些类。要添加多个类，请用空格分隔它们：`'class-1 class-2'`. 您还可以传递一个函数，该函数应返回包含其他类名的单个字符串。
`sanitize`	布尔值	`true`	启用或禁用清理。如果激活`'template'`并且`'title'`选项将被清理。请参阅我们的 JavaScript 文档中的消毒剂部分。
`allowList`	目的	默认值	包含允许的属性和标签的对象
`sanitizeFn`	空 \| 功能	`null`	在这里，您可以提供自己的消毒功能。如果您更喜欢使用专用库来执行清理，这会很有用。
`offset`	数组 \| 字符串 \| 功能	`[0, 0]`	工具提示相对于其目标的偏移量。您可以使用逗号分隔值在数据属性中传递字符串，例如：`data-bs-offset="10,20"` 当一个函数用于确定偏移量时，调用它时会使用一个包含 popper 放置、引用和 popper rects 作为其第一个参数的对象。触发元素 DOM 节点作为第二个参数传递。该函数必须返回一个包含两个数字的数组：.`[skidding, distance]` 有关更多信息，请参阅 Popper 的偏移量文档。
`popperConfig`	空 \| 对象 \| 功能	`null`	要更改 Bootstrap 的默认 Popper 配置，请参阅Popper 的配置。当一个函数用于创建 Popper 配置时，它会被一个包含 Bootstrap 的默认 Popper 配置的对象调用。它可以帮助您使用默认设置并将其与您自己的配置合并。该函数必须为 Popper 返回一个配置对象。

单个工具提示的数据属性

如上所述，可以通过使用数据属性来指定单个工具提示的选项。

使用函数`popperConfig`

var tooltip = new bootstrap.Tooltip(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

方法

异步方法和转换

所有 API 方法都是异步的并开始一个转换。他们在转换开始但在结束之前立即返回给调用者。此外，过渡组件上的方法调用将被忽略。

有关更多信息，请参阅我们的 JavaScript 文档。

节目

显示元素的工具提示。在工具提示实际显示之前（即在事件发生之前）返回给调用者。shown.bs.tooltip这被认为是工具提示的“手动”触发。从不显示具有零长度标题的工具提示。

tooltip.show()

隐藏

隐藏元素的工具提示。在工具提示实际上被隐藏之前（即在事件发生之前）返回给调用者。hidden.bs.tooltip这被认为是工具提示的“手动”触发。

tooltip.hide()

切换

切换元素的工具提示。在工具提示实际显示或隐藏之前（即在or事件发生之前）返回给调用者。这被认为是工具提示的“手动”触发。shown.bs.tooltiphidden.bs.tooltip

tooltip.toggle()

处置

隐藏和销毁元素的工具提示（删除 DOM 元素上存储的数据）。使用委托（使用选项创建）的selector工具提示不能在后代触发器元素上单独销毁。

tooltip.dispose()

使能够

使元素的工具提示能够显示。默认情况下启用工具提示。

tooltip.enable()

禁用

移除显示元素工具提示的能力。工具提示只有在重新启用后才能显示。

tooltip.disable()

切换启用

切换显示或隐藏元素工具提示的能力。

tooltip.toggleEnabled()

更新

更新元素工具提示的位置。

tooltip.update()

获取实例

允许您获取与 DOM 元素关联的工具提示实例的静态方法

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance

获取或创建实例

静态方法，允许您获取与 DOM 元素关联的工具提示实例，或创建一个新的实例以防它未初始化

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance

活动

事件类型	描述
`show.bs.tooltip`	`show`调用实例方法时立即触发此事件。
`shown.bs.tooltip`	当工具提示对用户可见时触发此事件（将等待 CSS 转换完成）。
`hide.bs.tooltip`	`hide`调用实例方法时立即触发此事件。
`hidden.bs.tooltip`	当工具提示完成对用户隐藏时触发此事件（将等待 CSS 转换完成）。
`inserted.bs.tooltip`	此事件`show.bs.tooltip`在工具提示模板添加到 DOM 的事件之后触发。

var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
  // do something...
})

tooltip.hide()