跳到主题内容 跳到文档导航栏

工具提示框(Tooltips)

有关使用CSS和JavaScript通过CSS3和JavaScript添加自定义Bootstrap工具提示的文档和示例，其中CSS3用于动画，而data-bs-attributes用于本地标题存储。

在本页面

概述

使用工具提示插件时应注意的事项：

  • 工具提示依赖于第三方库 Popper 进行定位。你必须在bootstrap.js之前包含 popper.min.js 或使用 bootstrap.bundle.min.js / bootstrap.bundle.js包含Popper以便工具提示起作用！
  • 由于性能原因，工具提示是可选的，因此您必须自己初始化它们。
  • 标题长度为零的工具提示永远不会显示。
  • 指定 container: 'body' 以避免在更复杂的组件（如输入组、按钮组等）中呈现问题。
  • 在隐藏元素上触发工具提示将不起作用。
  • .disabled 或 disabled 元素的工具提示必须在包装器元素上触发。
  • 当从跨多行的超链接触发时，工具提示将居中显示。在<a> 上使用 white-space: nowrap; ，以避免这种行为。
  • 在从DOM中删除相应的元素之前，必须隐藏工具提示。
  • 借助阴影DOM中的元素，可以触发工具提示。
此组件的动画效果取决于 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)
})

示例

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

Tight pants next level keffiyeh you probably haven't heard of them. Photo booth beard raw denim letterpress vegan messenger bag stumptown. Farm-to-table seitan, mcsweeney's fixie sustainable quinoa 8-bit american apparel have a terry richardson vinyl chambray. Beard stumptown, cardigans banh mi lomo thundercats. Tofu biodiesel williamsburg marfa, four loko mcsweeney's cleanse vegan chambray. A really ironic artisan whatever keytar, scenester farm-to-table banksy Austin twitter handle freegan cred raw denim single-origin coffee viral.

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

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

用法

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

通过JavaScript触发工具提示：

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
溢出 auto 和 scroll

当父容器像 .table-responsive一样发生overflow: auto 或 overflow: scroll 时，工具提示位置尝试自动更改， 但仍保持原始位置的位置。若要解析，请将 boundary选项设置为除默认值 'scrollParent'以外的任何值，例如 'window'：

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
  boundary: 'window'
})

标记

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

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

您应该只将工具提示添加到传统上以键盘为中心且具有交互性的HTML元素（例如链接或表单控件）。尽管通过添加tabindex="0"属性可以使任意HTML元素（如 <span>）成为焦点，但这将为键盘用户在非交互元素上添加潜在的恼人和混乱的制表位，并且大多数辅助技术目前都不会在这种情况下公布工具提示。另外，不要仅仅依靠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 属性的元素不是交互式的，这意味着用户不能聚焦、悬停或单击它们来触发工具提示（或popover）。作为解决方法，您需要从包装器 <div> 或 <span>触发工具提示，理想情况下使用 tabindex="0"使键盘可聚焦，并覆盖禁用元素上的 pointer-events。

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

选项

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

请注意，出于安全原因，不能使用数据属性提供 sanitize、 sanitizeFn 和 allowList 选项。
名称 类型 默认值 描述
animation boolean true 对工具提示应用CSS淡入淡出过渡。
container string | element | false false

将工具提示附加到特定元素。示例：container: 'body'。此选项特别有用，因为它允许您将工具提示放置在触发元素附近的文档流中—这将防止工具提示在调整窗口大小期间从触发元素中浮动。
delay number | object 0

延迟显示和隐藏工具提示（ms）-不适用于手动触发器类型。

如果提供了数字，则对隐藏/显示都应用延迟。

对象结构是 delay: { "show": 500, "hide": 100 }
html boolean false

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

如果为true，则工具提示title中的HTML标记将呈现在工具提示中。如果为false，innerText 属性将用于将内容插入DOM。

如果您担心XSS攻击，请使用文本。
placement string | function 'top'

如何定位工具提示-自动|顶部|底部|左侧|右侧。
当指定 auto时，它将动态地重定向工具提示。

当函数用于确定位置时，调用它时，工具提示DOM节点作为第一个参数，触发元素DOM节点作为第二个参数。 this上下文设置为工具提示实例。
selector string | false false 如果提供了选择器，则工具提示对象将委派给指定的目标。在实践中，它还用于将工具提示应用于动态添加的DOM元素（jQuery.on）。请看这个和一个信息丰富的例子。
template string '<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 string | element | function ''

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

如果给定了一个函数，将调用该函数，并将其this 引用设置为工具提示所附加到的元素。
trigger string 'hover focus'

如何触发工具提示-单击“悬停”“聚焦”“手动”。您可以传递多个触发器；用空格分隔它们。

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

'hover' 本身将导致无法通过键盘触发的工具提示，并且仅当存在用于向键盘用户传递相同信息的替代方法时才应使用。
fallbackPlacement null | array null 允许指定Popper在回退时使用的位置。有关更多信息，请参阅 Popper的行为文档。
boundary string | element 'clippingParents' 工具提示的溢出约束边界。默认情况下，它是'clippingParents' ，可以接受HTMLElement引用（仅限于JavaScript）。有关更多信息，请参阅 Popper的 preventOverflow 文档。
customClass string | function ''

在显示工具提示时向其添加类。请注意，这些类将添加到模板中指定的任何类之外。要添加多个类，请用空格分隔它们： 'class-1 class-2'。

还可以传递一个函数，该函数应返回一个包含其他类名的字符串。
sanitize boolean true 启用或禁用消除。如果激活， 'template' 和 'title' 选项将被清除。
allowList object Default value 包含允许的属性和标记的对象。
sanitizeFn null | function null 在这里您可以提供自己的消除函数。如果您喜欢使用专用的库来执行清理，这将非常有用。
popperConfig null | object null 要更改Bootstrap的默认Popper配置，请参阅 Popper的配置。

单个工具提示的数据属性

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

方法

异步方法和转换

所有API方法都是异步的， 并开始转换。 转换一开始就返回到调用方，但在转换结束之前返回。此外，对转换组件的方法调用将被忽略。

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

show

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

tooltip.show()

hide

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

tooltip.hide()

toggle

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

tooltip.toggle()

dispose

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

tooltip.dispose()

enable

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

tooltip.enable()

disable

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

tooltip.disable()

toggleEnabled

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

tooltip.toggleEnabled()

update

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

tooltip.update()

getInstance

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

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(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 当工具提示模板已添加到DOM时，会在show.bs.tooltip事件发生后触发此事件。 
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

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

tooltip.hide()