跳到主要内容 跳到文档导航
Check
in English

工具提示

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

在本页面

概述

使用工具提示插件时要知道的事情：

  • Tooltips 依赖第三方库Popper进行定位。您必须在之前包含popper.min.jsbootstrap.js，或者使用bootstrap.bundle.min.js包含 Popper 的一个。
  • 出于性能原因，工具提示是可选的，因此您必须自己初始化它们。
  • 从不显示具有零长度标题的工具提示。
  • 指定container: 'body'以避免在更复杂的组件（如我们的输入组、按钮组等）中出现渲染问题。
  • 在隐藏元素上触发工具提示将不起作用。
  • .disabled或元素的工具提示disabled必须在包装元素上触发。
  • 当从跨越多行的超链接触发时，工具提示将居中。white-space: nowrap;在你的 s 上使用<a>以避免这种行为。
  • 在从 DOM 中删除相应元素之前，必须隐藏工具提示。
  • 由于影子 DOM 中的元素，可以触发工具提示。

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

默认情况下，该组件使用内置的内容清理器，它会去除任何未明确允许的 HTML 元素。有关更多详细信息 ，请参阅 我们的 JavaScript 文档中的 sanitizer 部分。
该组件的动画效果依赖于 prefers-reduced-motion媒体查询。请参阅 我们可访问性文档的减少运动部分。

例子

启用工具提示

如上所述，您必须先初始化工具提示，然后才能使用它们。初始化页面上所有工具提示的一种方法是通过它们的data-bs-toggle属性来选择它们，如下所示：

const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl))

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

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

html 
<p class="muted">Placeholder text to demonstrate some <a href="#" data-bs-toggle="tooltip" data-bs-title="Default tooltip">inline links</a> with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of <a href="#" data-bs-toggle="tooltip" data-bs-title="Another tooltip">real text</a>. 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 <a href="#" data-bs-toggle="tooltip" data-bs-title="Another one here too">these tooltips on links</a> can work in practice, once you use them on <a href="#" data-bs-toggle="tooltip" data-bs-title="The last tip!">your own</a> site or project.
</p>
随意使用 title或 data-bs-title在您的 HTML 中使用。使用时 title，Popper 会自动替换 data-bs-title为元素渲染时。

自定义工具提示

在 v5.2.0 中添加

您可以使用CSS 变量自定义工具提示的外观。我们设置了一个自定义类data-bs-custom-class="custom-tooltip"来限定我们的自定义外观并使用它来覆盖本地 CSS 变量。

.custom-tooltip {
  --bs-tooltip-bg: var(--bs-primary);
}
html 
<button type="button" class="btn btn-secondary"
        data-bs-toggle="tooltip" data-bs-placement="top"
        data-bs-custom-class="custom-tooltip"
        data-bs-title="This top tooltip is themed via CSS variables.">
  Custom tooltip
</button>

方向

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

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

并添加了自定义 HTML：

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

使用 SVG：

CSS

变量

在 v5.2.0 中添加

作为 Bootstrap 不断发展的 CSS 变量方法的一部分，工具提示现在使用本地 CSS 变量.tooltip来增强实时自定义。CSS 变量的值是通过 Sass 设置的，因此仍然支持 Sass 自定义。

  --#{$prefix}tooltip-zindex: #{$zindex-tooltip};
  --#{$prefix}tooltip-max-width: #{$tooltip-max-width};
  --#{$prefix}tooltip-padding-x: #{$tooltip-padding-x};
  --#{$prefix}tooltip-padding-y: #{$tooltip-padding-y};
  --#{$prefix}tooltip-margin: #{$tooltip-margin};
  @include rfs($tooltip-font-size, --#{$prefix}tooltip-font-size);
  --#{$prefix}tooltip-color: #{$tooltip-color};
  --#{$prefix}tooltip-bg: #{$tooltip-bg};
  --#{$prefix}tooltip-border-radius: #{$tooltip-border-radius};
  --#{$prefix}tooltip-opacity: #{$tooltip-opacity};
  --#{$prefix}tooltip-arrow-width: #{$tooltip-arrow-width};
  --#{$prefix}tooltip-arrow-height: #{$tooltip-arrow-height};

Sass 变量

$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 * .25;
$tooltip-padding-x:                 $spacer * .5;
$tooltip-margin:                    null; // TODO: remove this in v6

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
// fusv-disable
$tooltip-arrow-color:               null; // Deprecated in Bootstrap 5.2.0 for CSS variables
// fusv-enable

用法

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

通过 JavaScript 触发工具提示：

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

当父容器有overflow: auto或overflow: scroll喜欢我们的时，工具提示位置会尝试自动更改.table-responsive，但仍保持原始位置的定位。要解决此问题，请将boundary选项（使用popperConfig选项的翻转修饰符）设置为任何 HTMLElement 以覆盖默认值'clippingParents'，例如document.body：

const tooltip = new bootstrap.Tooltip('#example', {
  boundary: document.body // or document.querySelector('#boundary')
})

标记

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

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

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

<!-- HTML to write -->
<a href="#" data-bs-toggle="tooltip" data-bs-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".

html 
<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" data-bs-title="Disabled tooltip">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

选项

由于选项可以通过数据属性或 JavaScript 传递，因此您可以将选项名称附加到data-bs-，如data-bs-animation="{value}". 通过数据属性传递选项时，请确保将选项名称的大小写类型从“ camelCase ”更改为“ kebab-case ”。例如，使用data-bs-custom-class="beautifier"代替data-bs-customClass="beautifier".

从 Bootstrap 5.2.0 开始，所有组件都支持一个实验性的保留数据属性data-bs-config，该属性可以将简单的组件配置作为 JSON 字符串容纳。当一个元素具有data-bs-config='{"delay":0, "title":123}'和data-bs-title="456"属性时，最终title值将是456并且单独的数据属性将覆盖给定的值 on data-bs-config。此外，现有数据属性能够容纳 JSON 值，例如data-bs-delay='{"show":0,"hide":150}'.

请注意，出于安全原因 sanitize， 不能使用数据属性提供 sanitizeFn、 和 选项。allowList
姓名 类型 默认 描述
allowList 目的 默认值 包含允许的属性和标签的对象。
animation 布尔值 true 对工具提示应用 CSS 淡入淡出过渡。
boundary 字符串，元素 'clippingParents' 工具提示的溢出约束边界（仅适用于 Popper 的 preventOverflow 修饰符）。默认情况下，它'clippingParents'可以接受 HTMLElement 引用（仅通过 JavaScript）。有关更多信息，请参阅 Popper 的detectOverflow 文档。
container 字符串，元素，假 false 将工具提示附加到特定元素。示例：container: 'body'。此选项特别有用，因为它允许您将工具提示定位在文档流中靠近触发元素的位置 - 这将防止工具提示在窗口调整大小期间从触发元素浮动。
customClass 字符串，函数 '' 显示时将类添加到工具提示。请注意，除了模板中指定的任何类之外，还将添加这些类。要添加多个类，请用空格分隔它们：'class-1 class-2'. 您还可以传递一个函数，该函数应返回包含其他类名的单个字符串。
delay 数字，对象 0 延迟显示和隐藏工具提示（毫秒）—不适用于手动触发类型。如果提供了一个数字，则延迟将应用于隐藏/显示。对象结构为：delay: { "show": 500, "hide": 100 }.
fallbackPlacements 大批 ['top', 'right', 'bottom', 'left'] 通过提供数组中的展示位置列表（按优先顺序）来定义后备展示位置。有关更多信息，请参阅 Popper 的行为文档。
html 布尔值 false 在工具提示中允许 HTML。如果为 true，则工具提示中的 HTML 标记title将在工具提示中呈现。如果为 false，innerText属性将用于将内容插入 DOM。如果您担心 XSS 攻击，请使用文本。
offset 数组、字符串、函数 [0, 0] 工具提示相对于其目标的偏移量。您可以使用逗号分隔值在数据属性中传递字符串，例如：data-bs-offset="10,20"。当一个函数用于确定偏移量时，调用它时会使用一个包含 popper 放置、引用和 popper rects 作为其第一个参数的对象。触发元素 DOM 节点作为第二个参数传递。该函数必须返回一个包含两个数字的数组：skidding、distance。有关更多信息，请参阅 Popper 的偏移量文档。
placement 字符串，函数 'top' 如何定位工具提示：自动、上、下、左、右。指定时auto，它将动态地重新定向工具提示。当一个函数用于确定位置时，它会以工具提示 DOM 节点作为其第一个参数，触发元素 DOM 节点作为其第二个参数来调用。this上下文设置为工具提示实例。
popperConfig 空，对象，函数 null 要更改 Bootstrap 的默认 Popper 配置，请参阅Popper 的配置。当一个函数用于创建 Popper 配置时，它会被一个包含 Bootstrap 的默认 Popper 配置的对象调用。它可以帮助您使用默认设置并将其与您自己的配置合并。该函数必须为 Popper 返回一个配置对象。
sanitize 布尔值 true 启用或禁用清理。如果激活'template'，选项将被清理'content'。'title'
sanitizeFn 空，函数 null 在这里，您可以提供自己的消毒功能。如果您更喜欢使用专用库来执行清理，这会很有用。
selector 字符串，假 false 如果提供了选择器，则工具提示对象将被委托给指定的目标。在实践中，这也用于将工具提示应用于动态添加的 DOM 元素（jQuery.on支持）。请参阅此问题和内容丰富的示例。
template 细绳 '<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 字符串、元素、函数 '' title如果属性不存在，则默认标题值。如果给定了一个函数，它将被调用，并将其this引用设置为弹出框附加到的元素。
trigger 细绳 'hover focus' 工具提示的触发方式：单击、悬停、聚焦、手动。您可以传递多个触发器；用空格分隔它们。'manual'指示工具提示将通过.tooltip('show'),.tooltip('hide')和.tooltip('toggle')方法以编程方式触发；此值不能与任何其他触发器组合。'hover'其本身将导致无法通过键盘触发的工具提示，并且仅应在存在为键盘用户传达相同信息的替代方法时使用。

单个工具提示的数据属性

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

使用函数popperConfig 

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

方法

异步方法和转换

所有 API 方法都是异步的并开始一个转换。他们在转换开始但在结束之前立即返回给调用者。此外，过渡组件上的方法调用将被忽略。

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

方法 描述
disable 移除显示元素工具提示的能力。工具提示只有在重新启用后才能显示。
dispose 隐藏和销毁元素的工具提示（删除 DOM 元素上存储的数据）。使用委托（使用选项创建）的selector工具提示不能在后代触发器元素上单独销毁。
enable 使元素的工具提示能够显示。默认情况下启用工具提示。
getInstance 静态方法，允许您获取与 DOM 元素关联的工具提示实例，或创建一个新实例以防它未初始化。
getOrCreateInstance 静态方法，允许您获取与 DOM 元素关联的工具提示实例，或创建一个新实例以防它未初始化。
hide 隐藏元素的工具提示。在工具提示实际上被隐藏之前（即在事件发生之前）返回给调用者。hidden.bs.tooltip这被认为是工具提示的“手动”触发。
setContent 提供一种在初始化后更改工具提示内容的方法。
show 显示元素的工具提示。在工具提示实际显示之前（即在事件发生之前）返回给调用者。shown.bs.tooltip这被认为是工具提示的“手动”触发。从不显示具有零长度标题的工具提示。
toggle 切换元素的工具提示。在工具提示实际显示或隐藏之前（即在or事件发生之前）返回给调用者。这被认为是工具提示的“手动”触发。shown.bs.tooltiphidden.bs.tooltip
toggleEnabled 切换显示或隐藏元素工具提示的能力。
update 更新元素工具提示的位置。 
const tooltip = bootstrap.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })
该 setContent方法接受一个 object参数，其中每个属性键都是 string弹出框模板中的有效选择器，每个相关的属性值可以是 string| element| function| null

活动

事件 描述
hide.bs.tooltip hide调用实例方法时立即触发此事件。
hidden.bs.tooltip 当弹出窗口完成对用户隐藏时触发此事件（将等待 CSS 转换完成）​​。
inserted.bs.tooltip 此事件show.bs.tooltip在工具提示模板添加到 DOM 的事件之后触发。
show.bs.tooltip show调用实例方法时立即触发此事件。
shown.bs.tooltip 当弹出框对用户可见时触发此事件（将等待 CSS 转换完成）​​。 
const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

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

tooltip.hide()