在GitHub上查看

提示冒泡

在文档和例子中添加自定义Bootstrap提示工具与CSS3 和 在JavaScript中使用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 媒体查询。 请参阅reduced motion section of our accessibility documentation.

了解了所有吗?很好，让我们通过一些例子来看看它们是如何工作的。

启用提示工具

初始化页面上所有提示工具的一种方法是通过 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 的溢出

提示工具的配置尝试自动改变当前父容器 overflow: auto 或 overflow: scroll 像我们的 .table-responsive，但仍然保持原来的位置。要解决这个问题，可以将 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 属性的元素是不可交互的，这意味着用户不能聚焦、悬停或单击它们来触发提示工具（或弹出窗口）。有一种解决方法， 您需要从 <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 | top | bottom | left | right。 当指定了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'

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

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

'hover' 本身将导致无法通过键盘触发的提示工具，只有在有其他方法向键盘用户传达相同信息时才可以使用。
fallbackPlacement null | array null 允许指定Popper在回退时使用的位置。更多信息请参考Popper的behavior 文档
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文档。.

显示

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

tooltip.show()

隐藏

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

tooltip.hide()

切换

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

tooltip.toggle()

处置

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

tooltip.dispose()

启用

为元素的工具提示提供显示的能力。提示工具默认是启用的。

tooltip.enable()

禁用

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

tooltip.disable()

启用开关

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

tooltip.启用开关()

更新

更新提示工具的位置。

tooltip.update()

获取实例

静态方法，它允许您获得与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 这个事件在 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()