工具提示（Tooltips）

如何透过CSS与Javascript添加自定义Bootstrap工具提示的文件与示例。其中CSS3用于动画，data-bs-attributes用于用于本地标题的储存。

On this page

概述

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

  • 工具提示依赖于第三方库Popper进行定位。您必须在bootstrap.js之前包含popper.min.js，或者使用bootstrap.bundle.min.js/bootstrap.bundle.js，其中包含popper，这样工具提示才能工作！
  • 由于性能原因，工具提示是可选的，因此您必须自己初始化它们。
  • 标题长度为零的工具提示永远不会显示。
  • 指定container:'body'以避免在更复杂的组件（如输入组、按钮组等）中呈现问题。
  • 在隐藏元素上触发工具提示将不起作用。
  • .disabled或disabled元素的工具提示必须在包装器元素上触发。
  • 当从跨多行的超链接触发时，工具提示将居中显示。使用空白：nowrap；以避免这种行为。
  • 在从DOM中删除相应的元素之前，必须隐藏工具提示。
  • 由于阴影DOM中的元素，可以触发工具提示。
默认情况下，此组件使用内置的内容清理器，该清理器将删除任何不明确允许的HTML元素。有关更多详细信息，请参阅JavaScript文档中的“消毒液”部分。
该组件的动画效果取决于偏好减少的运动媒体查询。请参阅我们的可访问性文档的简化运动部分。

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

示例：在各处用工具提示

初始化页面上所有工具提示的一种方法是通过数据属性选择它们：

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

示例

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

Placeholder text to demonstrate some inline links with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of real text. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you've now seen how these tooltips on links can work in practice, once you use them on your own site or project.

将鼠标悬停在下面的按钮上可以看到四个工具提示方向：顶部、右侧、底部和左侧。在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:

Sass

Variables

$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 / 4;
        $tooltip-padding-x:                 $spacer / 2;
        $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)
溢出自动和滚动

当父容器发生溢出时，工具提示位置尝试自动更改：自动或溢出：像.table一样滚动，但仍保持原始位置的位置。若要解析，请将边界选项设置为除默认值“scrollParent”以外的任何值，例如“window”：

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

标记

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

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

您应该只为传统上可被键盘focus以及可互动（如连接或表单控制元件）的HTML元素添加工具提示。虽然任意的HTML元素（如span）可以透过添加tabindex=“0”属性使其可以被focus，但这会为键盘使用者的非互动式元素增加可能造成困惑的定位点。且大多数的辅助技术目前还不会推播这种工具提示。此外，不要单纯依赖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”使键盘可聚焦。 

<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=""中所示。在传递数据属性时，请确保将选项名称的case类型从camelCase更改为kebab case。例如：不要使用数据data-bs-customClass="beautifier"，而是使用数据 data-bs-custom-class="beautifier"。

请注意，出于安全原因，不能使用数据属性提供sanitize、sanitizeFn和allowList选项。
Name Type Default Description
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，则工具提示标题中的HTML标记将呈现在工具提示中。如果为false，innerText属性将用于将内容插入DOM。

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

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

函数用于确定位置时，调用它时，工具提示DOM节点作为第一个参数，触发元素DOM节点作为第二个参数。此上下文设置为工具提示实例。
selector string | false false 如果提供了选择器，则工具提示对象将委派给指定的目标。实际上，它还用于将工具提示应用于动态添加的DOM元素（jQuery.on support）。请看这个和一个信息丰富的例子。 this and an informative example.
template string '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'

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

工具提示的标题将被注入.tooltip内部。

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

最外层的包装器元素应该具有.tooltip类和role=“tooltip”。

title string | element | function ''

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

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

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

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

“悬停”本身将导致无法通过键盘触发的工具提示，并且仅当存在用于向键盘用户传递相同信息的替代方法时才应使用。

fallbackPlacements array ['top', 'right', 'bottom', 'left'] 通过提供数组中的放置列表（按优先顺序）来定义后备放置。有关更多信息，请参阅波普尔的行为文档 behavior docs
boundary string | element 'clippingParents' 工具提示的溢出约束边界。默认情况下，它是'clippingParents'，可以接受HTMLElement引用（仅限于JavaScript）。有关更多信息，请参阅波普尔的文件。 preventOverflow docs.
customClass string | function ''

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

还可以传递一个函数，该函数应返回一个包含其他类名的字符串。
sanitize boolean true 启用或禁用消毒。如果激活，“模板”和“标题”选项将被清除。请参阅我们的JavaScript文档中的消毒剂部分。
allowList object Default value 包含允许的属性和标记的对象
sanitizeFn null | function null 在这里您可以提供自己的消毒功能。如果您喜欢使用专用的库来执行清理，这将非常有用。
offset array | string | function [0, 0]

工具提示相对于其目标的偏移量。您可以用逗号分隔的值在数据属性中传递字符串，例如：data bs offset=“10,20”

当一个函数用于确定偏移量时，调用它的第一个参数是包含popper放置、引用和popper rects的对象。触发元素DOM node作为第二个参数传递。函数必须返回一个包含两个数字的数组：[滑动，距离]。

F有关更多信息，请参阅offset docs.
popperConfig null | object | function null

T要更改引导的默认Popper配置，请参阅Popper的配置。 Popper's configuration.

当一个函数被用来创建Popper配置时，它被一个包含引导的默认Popper配置的对象调用。它可以帮助您使用默认配置并将其与您自己的配置合并。函数必须返回Popper的配置对象。

单个工具提示的数据属性

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

Using function with popperConfig

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

方法

异步方法和转换

所有API方法都是异步的，并开始转换。转换一开始就返回到调用方，但在转换结束之前返回。此外，对转换组件的方法调用将被忽略。 有关更多信息，请参阅我们的JavaScript文档。

显示

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

tooltip.show()

隐藏

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

tooltip.hide()

切换

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

tooltip.toggle()

注销

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

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

事件

Event type Description
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()
返回顶部