在 GitHub 上查看

工具提示

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

概述

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

  • 工具提示依赖第三方库 Popper 进行定位。您必须在 bootstrap.js 之前包含 popper.min.js，或使用包含 Popper 的 bootstrap.bundle.min.js / bootstrap.bundle.js，才能使工具提示正常工作！
  • 如果您从源代码构建 JavaScript，它需要 util.js。
  • 出于性能原因，工具提示是选择加入的，因此您必须自己初始化它们。
  • 标题长度为零的工具提示永远不会显示。
  • 指定 container: 'body' 以避免在更复杂的组件（如我们的输入组、按钮组等）中出现渲染问题。
  • 在隐藏元素上触发工具提示不起作用。
  • 针对 .disabled 或 disabled 元素的工具提示必须在包装元素上触发。
  • 当从跨多行的超链接触发时，工具提示将居中。在 <a> 上使用 white-space: nowrap; 以避免此行为。
  • 必须在从 DOM 中删除相应元素之前隐藏工具提示。
  • 可以借助阴影 DOM 中的元素触发工具提示。
默认情况下，此组件使用内置的内容清理器，它会清除任何未明确允许的 HTML 元素。有关更多详细信息，请参阅 JavaScript 文档中的清理器部分。
此组件的动画效果取决于 prefers-reduced-motion 媒体查询。请参阅 无障碍文档中的减少动作部分。

都了解了吗？太好了，让我们通过一些示例看看它们如何工作。

示例：在任意位置启用工具提示

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

$(function () {
  $('[data-toggle="tooltip"]').tooltip()
})

示例

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

占位符文本用于演示一些带有工具提示的 内联链接。这现在只是填充物，没有杀手锏。放置在此处的内容只是为了模仿 真实文本 的存在。所有这些只是为了让您了解在实际情况下使用工具提示时的外观。因此，希望您现在已经看到 链接上的这些工具提示 在实践中如何工作，一旦您在 您自己的 网站或项目上使用它们。

将鼠标悬停在下面的按钮上以查看四个工具提示方向：顶部、右侧、底部和左侧。

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

并添加自定义 HTML

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

用法

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

通过 JavaScript 触发工具提示

$('#example').tooltip(options)
溢出 auto 和 scroll

当父容器具有 overflow: auto 或 overflow: scroll（如我们的 .table-responsive）时，工具提示位置会尝试自动更改，但仍保留原始位置的定位。要解决此问题，请将 boundary 选项设置为除默认值 'scrollParent' 之外的任何值，例如 'window'

$('#example').tooltip({ boundary: 'window' })

标记

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

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

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

<!-- HTML to write -->
<a href="#" data-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="arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

禁用元素

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

<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="Disabled tooltip">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

选项

选项可以通过数据属性或 JavaScript 传递。对于数据属性，将选项名称附加到 data-，如 data-animation=""。

请注意，出于安全原因， sanitize、 sanitizeFn 和 whiteList 选项不能使用数据属性提供。
名称 类型 默认值 说明
animation 布尔值 true 对工具提示应用 CSS 渐显过渡
container 字符串 | 元素 | false false

将工具提示附加到特定元素。示例： container: 'body'。此选项特别有用，因为它允许您将工具提示定位在触发元素附近的文档流中 - 这将防止工具提示在窗口调整大小时远离触发元素。
delay 数字 | 对象 0

显示和隐藏工具提示的延迟（毫秒） - 不适用于手动触发类型

如果提供数字，则延迟将应用于隐藏/显示

对象结构为：delay: { "show": 500, "hide": 100 }
html 布尔值 false

允许在工具提示中使用 HTML。

如果为 true，则工具提示的 title 中的 HTML 标记将在工具提示中呈现。如果为 false，则将使用 jQuery 的 text 方法将内容插入 DOM。

如果您担心 XSS 攻击，请使用文本。
placement 字符串 | 函数 'top'

如何定位工具提示 - auto | top | bottom | left | right。
当指定 auto 时，它将动态重新定向工具提示。

当使用函数确定位置时，它将以工具提示 DOM 节点作为其第一个参数，以触发元素 DOM 节点作为其第二个参数来调用。this 上下文设置为工具提示实例。
selector 字符串 | false false 如果提供了选择器，则工具提示对象将委托给指定的 target。实际上，这用于将工具提示应用于动态添加的 DOM 元素（jQuery.on 支持）。请参阅 此处 和 一个信息丰富的示例。
template 字符串 '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

创建工具提示时要使用的基本 HTML。

工具提示的 title 将注入到 .tooltip-inner 中。

.arrow 将成为工具提示的箭头。

最外层的包装元素应具有 .tooltip 类和 role="tooltip"。
title 字符串 | 元素 | 函数 ''

如果 title 属性不存在，则为默认标题值。

如果给定了一个函数，则将使用其 this 引用集调用它，该引用集设置为附加工具提示的元素。
trigger 字符串 'hover focus'

如何触发工具提示 - click | hover | focus | manual。您可以传递多个触发器；用空格分隔它们。

'manual' 表示将通过 .tooltip('show')、.tooltip('hide') 和 .tooltip('toggle') 方法以编程方式触发工具提示；此值不能与任何其他触发器结合使用。

单独使用 'hover' 将导致无法通过键盘触发的工具提示，并且仅应在存在用于向键盘用户传达相同信息的替代方法时使用。
offset 数字 | 字符串 | 函数 0

工具提示相对于其目标的偏移量。

当使用函数确定偏移量时，它将以包含偏移量数据作为其第一个参数的对象进行调用。函数必须返回具有相同结构的对象。触发元素 DOM 节点作为第二个参数传递。

有关更多信息，请参阅 Popper 的 偏移量文档。
fallbackPlacement 字符串 | 数组 '翻转' 允许指定 Popper 在后备时将使用哪个位置。有关更多信息，请参阅 Popper 的 行为文档
customClass 字符串 | 函数 ''

当工具提示显示时，向其添加类。请注意，这些类将添加到模板中指定的任何类中。要添加多个类，请使用空格分隔它们：'a b'。

您还可以传递一个函数，该函数应返回一个包含其他类名的单个字符串。
boundary 字符串 | 元素 'scrollParent' 工具提示的溢出约束边界。接受 'viewport'、'window'、'scrollParent' 的值，或 HTMLElement 引用（仅限 JavaScript）。有关更多信息，请参阅 Popper 的 preventOverflow 文档。
sanitize 布尔值 true 启用或禁用清理。如果激活，将清理 'template' 和 'title' 选项。请参阅 JavaScript 文档中的清理部分。
whiteList 对象 默认值 包含允许的属性和标记的对象
sanitizeFn null | 函数 null 您可以在此处提供自己的清理函数。如果您希望使用专用库来执行清理，这将非常有用。
popperConfig null | 对象 null 要更改 Bootstrap 的默认 Popper 配置，请参阅 Popper 的配置

单个工具提示的数据属性

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

方法

异步方法和过渡

所有 API 方法都是 异步的，并启动 过渡。它们在过渡启动后立即返回给调用者，但在 过渡结束之前。此外，将 忽略对正在过渡的组件 的方法调用。

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

$().tooltip(options)

将工具提示处理程序附加到元素集合。

.tooltip('show')

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

$('#element').tooltip('show')

.tooltip('hide')

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

$('#element').tooltip('hide')

.tooltip('toggle')

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

$('#element').tooltip('toggle')

.tooltip('dispose')

隐藏并销毁元素的工具提示。使用委派（使用 selector 选项 创建）的工具提示无法在后代触发元素上单独销毁。

$('#element').tooltip('dispose')

.tooltip('enable')

赋予元素的工具提示显示的能力。默认情况下启用工具提示。

$('#element').tooltip('enable')

.tooltip('disable')

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

$('#element').tooltip('disable')

.tooltip('toggleEnabled')

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

$('#element').tooltip('toggleEnabled')

.tooltip('update')

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

$('#element').tooltip('update')

事件

事件类型 说明
show.bs.tooltip 当调用 show 实例方法时，此事件会立即触发。
shown.bs.tooltip 当工具提示对用户可见时，此事件会触发（会等待 CSS 过渡完成）。
hide.bs.tooltip 当调用 hide 实例方法时，此事件会立即触发。
hidden.bs.tooltip 当工具提示完成对用户隐藏时，此事件会触发（会等待 CSS 过渡完成）。
inserted.bs.tooltip 当工具提示模板已添加到 DOM 中时，此事件会在 show.bs.tooltip 事件后触发。 
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})