提示冒泡(Tooltip)

使用CSS3为CSS和JavaScript添加自定义Bootstrap工具提示的文档和示例，用于本地标题存储的动画和数据属性。

概览

使用提示冒泡持件时应了解以下：

  • Tooltip提示冒泡组件依赖于 Popper.js ，你必须将popper.min.js 文件放在 bootstrap.js之前调用，或者使用 bootstrap.bundle.min.js / bootstrap.bundle.js这两个已经包含了 Popper.js 的脚本。
  • 如果自行编译JS，请 包含 util.js文件。
  • 出于性能安排，Tooltip提示冒泡是一个可选插件，所以 你必须自己初始化它们。
  • 标题（或内容）零长度情况下，Tooltip提示冒泡插件不会显示（生效）。
  • 指定 container: 'body' 以避免复杂组年（如输入框组、按钮组等）中渲染呈出混乱（出问题）。
  • 在隐藏元素上触发Tooltip提示冒泡插件不会起作用（无效行为）。
  • Tooltip提示冒泡插件的.disabled 或 disabled 元素必须放在外层（父层）元素上。
  • 如果从一个跨多行的链接上触发Tooltip提示冒泡插件，提示冒泡将居中，在你的<a>上使用white-space: nowrap; 可避免这种行为（即回归左右对齐）。
  • 必须先隐藏Tooltip提示冒泡插件，然后才能从DOM中删除相应的元素。

此组件的动画效果取决于prefers-reduced-motion 媒体查询. 请参阅我们的 辅助功能文档的简化动作部分.

都明白了？很好。让我们来通过一些例子来看它们具体是如何运作的。

示例：在任何地方启用tooltip提示冒泡插件

在网页上初始化所有的tooltip提示冒泡插件一个途径就是用data-toggle 来选择它们：

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

实际范例

请用鼠标点击下面一段文字上的链接，查看tooltip提示冒泡效果：

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.

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

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

用法

tooltip提示冒泡插件根据需要生成内容和标记，默认情况下我们将它放在触发元素之后。

使用JavaScript触发提示冒泡：

$('#example').tooltip(options)
溢出自动和滚动

当父容器溢出时，工具提示位置会尝试自动更改:自动或 溢出， 像我们的.table-responsive一样滚动,但仍保留原始位置的定位. 要解决此问题, 请将boundary选项设置为默认值, 'scrollParent',例如'window':

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

标记

工具提示框所需要的标记只是一个data 元素和你希望拥有一个tooltip提示冒泡HTML元素上的 title ，tooltip提示冒泡插件的标记很简单，尽管它需要一个位置（默认是 top 顶部指示）。

使tooltip提示冒泡使用于键盘和辅助技术使用者

推荐你只为传统的键盘和互动式（如链接或表单控制元件）的HTML元素添加tooltip提示冒泡框，虽然任意的HTML 元素 (如 <span>)可以通过添加 tabindex="0" 属性来调整focus行为，但这会为键盘使用者的非互动式元素增加可能困惑（混乱/错误)的定位点。此外大多数辅助技术目前还没有加入这种情况下的提示冒泡效果支持。

<!-- 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 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选项.

名称 Type类型 默认值 描述
animation boolean true 将CSS淡入淡出应用于tooltip提示冒泡。
container string | element | false false

将tooltip提示冒泡框附加到特定的元素，如 container: 'body'.，该选项特别有用，因为它允许您将触模屏定位在触发元素附近的文字内容-这将防止在画面调整大小时，弹出的进示框远离触发元素。
delay number | object 0

显示和隐藏弹出提示框的延迟(ms)-不适用于手动触发类型。

如果向这个选项提供一个数字，隐藏/显示都会应用这个延迟。

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

在tooltip提示冒泡中插入HTML。

如果值为true,tooltip提示冒泡的 title 中HTML标签将在工具提示框中呈现。如果是 false, 则将使用jQuery的 text方法将内容插入到DOM中。

如果你担心XSS攻击，请使用text文字。
placement string | function 'top'

如何提示冒泡，包括： auto | top | bottom | left | right。
如何指定为 auto ，它会动态地调整提示冒泡的位置。举个例子，如果placement是`auto left`，提示冒泡将尽可能地显示在左侧，否则显示在右侧。

如果使用一个函数来定位时，将使用提示冒泡的DMO节点作为其第一个参数并将触发元素的DOM节点作为其第二个参数来调用，this 将被设为弹出提示框实例。
selector string | false false 如果提供了选择器，提示冒泡将被委派给指定的目标。在实践中，它让动态添加的HTMl内容也能附加提示框，看 这里 和 一个翔实的例子。
template string '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

在创建提示冒泡时使用HTMl。

tooltip提示冒泡的title值将被注入到.tooltip-inner中。

.arrow 将变成tooltip提示冒泡的指示箭头。

最外层的包裹元素应该有 .tooltip class样式选择器。
title string | element | function ''

如果 title 属性不存在，则提供默认的title值。

如果提供了一个函数，调用此函数时，此函数的 this 引用被设置为tooltip提示冒泡的元素。
trigger string 'hover focus' 如何触发提示冒泡 - click | hover | focus | manual.，你可以传递多个触发器，用空格隔开它们，但是`manual`不能与别的触发器结合使用。
offset number | string 0 提示冒泡框对于其目标的偏移，更多信息请参阅Popper.js的 偏移（约束）文档。
fallbackPlacement string | array 'flip' 指定提示冒泡框在回调时使用哪个位置，有关更多信息请参阅 Popper.js的 偏移（约束）文档。

单个提示冒泡的数据属性

单个提示冒泡的选项可以通过使用data数据属性来替补指定，如前文所述。

方法

异步传输和转换

所有的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')

给一个元素的提示冒泡显示的功能， 默认情况下启用Tooltip提示冒泡。

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

.tooltip('disable')

删除元素的提示冒泡的显示功能，只有在重新启用后，才能显示提示冒泡。

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

.tooltip('toggleEnabled')

切换元素的提示冒泡显示或隐藏的能力。

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

.tooltip('update')

更新tooltip提示冒泡的位置。

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

活动

Event事件类型 描述
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…
})