Skip to main content Skip to docs navigation
View on GitHub

工具提示（Tooltips）

使用 CSS3 制作动画并使用 data-bs-attributes 进行本地标题存储，通过 CSS 和 JavaScript 添加自定义 Bootstrap 工具提示的文档和示例。

On this page

概览

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

  • 工具提示依赖第三方库 Popper 进行定位。您必须在 bootstrap.js 之前包含popper.min.js，或使用包含 Popper 的 bootstrap.bundle.min.js。
  • 出于性能考虑，工具提示是选择性的，因此您必须自行初始化 。
  • 标题长度为零的工具提示永远不会显示。
  • 指定 container: 'body'，以避免在更复杂的组件（如输入组、按钮组等）中出现渲染问题。
  • 在隐藏元素上触发工具提示将不起作用。
  • 必须在包装元素上触发 .disabled 或 disabled 元素的工具提示。
  • 从跨多行的超链接触发时，工具提示将居中。 在您的 <a>s 上使用 white-space: nowrap; 以避免这种行为。
  • 工具提示必须在相应元素从 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))

链接上的工具提示

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

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.

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>
您可以在HTML中随意使用title或data-bs-title。使用title时，Popper会在渲染元素时自动将其替换为data-bs-title。

自定义工具提示

Added in v5.2.0

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

site/assets/scss/_component-examples.scss 
.custom-tooltip {
  --bs-tooltip-bg: var(--bd-violet-bg);
  --bs-tooltip-color: var(--bs-white);
}
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

变量

Added in v5.2.0

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

scss/_tooltip.scss 
--#{$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 变量

scss/_variables.scss 
$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     var(--#{$prefix}body-bg);
$tooltip-bg:                        var(--#{$prefix}emphasis-color);
$tooltip-border-radius:             var(--#{$prefix}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)

当父容器具有 overflow: auto 或 overflow: scroll 时，工具提示会自动尝试改变位置，但仍会保持原来的位置。将boundary选项（用于使用popperConfig选项的翻转修饰符）设置为任何 HTMLElement，以覆盖默认值'clippingParents'，例如document.body：

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

标记

工具提示所需的标记只有一个 data 属性和希望添加工具提示的 HTML 元素上的 title。生成的工具提示标记非常简单，但需要一个位置（插件默认设置为 top）。

只在传统上可通过键盘聚焦和交互的 HTML 元素（如链接或表单控件）上添加工具提示，以保持键盘和辅助技术用户 可访问工具提示。虽然可以通过添加 tabindex="0" 使其他 HTML 元素成为可聚焦元素，但这会在非交互式元素上为键盘用户创建恼人且令人困惑的制表符停止符，而且大多数辅助技术目前不会在这种情况下公布工具提示。此外，请勿完全依赖 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-auto" 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>

选项

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

从 Bootstrap 5.2.0 开始，所有组件都支持一个实验性预留data 属性 data-bs-config ，它可以将简单的组件配置以 JSON 字符串的形式存放。当一个元素具有data-bs-config='{“delay”:0, “title”:123}' 和 data-bs-title=“456” 属性时，最终的title值将是456，而单独的data 属性将覆盖data-bs-config上给出的值。此外，现有的data 属性还能容纳 JSON 值，如 data-bs-delay='{“show”:0, “hide”:150}'。

最终配置对象是 data-bs-config、data-bs- 和 js object 的合并结果，其中最新给定的键值优先于其他键值。

请注意，出于安全原因，sanitize, sanitizeFn, 和 allowList选项不能使用数据属性提供。
Name Type Default Description
allowList object Default value 包含允许属性和标记的对象。
animation boolean true 为工具提示应用 CSS 淡入淡出过渡。
boundary string, element 'clippingParents' 工具提示的溢出约束边界（仅适用于 Popper 的 preventOverflow 修改器）。默认情况下，它是'clippingParents'，并且可以接受 HTMLElement 引用（仅通过 JavaScript）。更多信息请参阅 Popper 的 detectOverflow docs。
container string, element, false false 将工具提示添加到特定元素。例如：container: 'body'。该选项特别有用，因为它可以将工具提示放置在文档流中靠近触发元素的位置 - 这样可以防止工具提示在窗口调整大小时从触发元素上飘走。
customClass string, function '' 在工具提示显示时为其添加类别。请注意，这些类将添加到模板中指定的任何类之外。要添加多个类，请用空格分隔：'class-1 class-2'。您也可以传递一个函数，该函数将返回一个包含其他类名的字符串。
delay number, object 0 显示和隐藏工具提示的延迟（毫秒）-不适用于手动触发类型。如果提供了数字，则隐藏/显示时都会应用延迟。对象结构为： delay： { "显示"： 500, "hide"： 100 }.
fallbackPlacements array ['top', 'right', 'bottom', 'left'] 通过提供数组中的位置列表（按优先级排序）来定义后备位置。更多信息请参阅 Popper 的 behavior docs。
html boolean false 允许在工具提示中使用 HTML。如果为 “true”，工具提示的 title 中的 HTML 标记将在工具提示中呈现。如果为假，将使用 innerText 属性在 DOM 中插入内容。如果担心 XSS 攻击，请使用文本。
offset array, string, function [0, 0] 工具提示相对于目标的偏移量。您可以在数据属性中传递一个以逗号分隔的字符串，例如 data-bs-offset="10,20". 当使用函数确定偏移量时，它的第一个参数是一个包含弹出窗口位置、引用和弹出窗口矩形的对象。触发元素 DOM 节点作为第二个参数传递。函数必须返回一个包含两个数字的数组： 滑动、距离。更多信息请参阅 Popper 的 offset docs。
placement string, function 'top' 如何定位工具提示：自动、上、下、左、右。指定 auto 时，将动态调整工具提示的方向。如果使用函数来确定工具提示的位置，则会以工具提示 DOM 节点作为第一个参数，以触发元素 DOM 节点作为第二个参数来调用该函数。this 上下文将设置为工具提示实例。
popperConfig null, object, function null 要更改 Bootstrap 的默认 Popper 配置，请参阅 Popper’s configuration。当使用函数创建 Popper 配置时，会调用一个包含 Bootstrap 默认 Popper 配置的对象。它可以帮助您使用默认配置并将其与自己的配置合并。函数必须返回一个 Popper 配置对象。
sanitize boolean true 启用或禁用清理。如果激活，'template'、'content' 和'title' 选项将被清理。
sanitizeFn null, function null 在这里，您可以提供自己的 sanitize 函数。如果您更喜欢使用专门的库来执行 sanitize，这将非常有用。
selector string, false false 如果提供了选择器，工具提示对象将被委托给指定的目标。实际上，这也用于将工具提示应用于动态添加的 DOM 元素（支持 jQuery.on）。请参见 this issue 和 an informative example. 注意： title 属性不得用作选择器。
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 '' 工具提示标题。如果给出一个函数，则在调用该函数时会将其 this 引用设置为弹出窗口所连接的元素。
trigger string '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 文档
Method Description
disable 移除显示元素工具提示的功能。工具提示只有在重新启用后才能显示。
dispose 隐藏并销毁元素的工具提示（删除 DOM 元素上存储的数据）。使用委托（使用selector选项创建）的工具提示不能在后代触发器元素上单独销毁。
enable 使元素的工具提示能够显示。默认启用工具提示。
getInstance 静态方法，用于获取与 DOM 元素相关联的工具提示实例，或在未初始化的情况下创建一个新实例。
getOrCreateInstance 静态方法，用于获取与 DOM 元素相关联的工具提示实例，或在未初始化的情况下创建一个新实例。
hide 隐藏元素的工具提示。在工具提示实际隐藏之前（即在 hidden.bs.tooltip 事件发生之前）返回给调用者。这被视为 “手动"触发工具提示。
setContent 提供了一种在初始化后更改工具提示内容的方法。
show 显示元素的工具提示。在工具提示实际显示之前（即在 shown.bs.tooltip 事件发生之前）返回给调用者。这被视为 “手动” 触发工具提示。标题长度为零的工具提示永远不会显示。
toggle 切换元素的工具提示。在工具提示实际显示或隐藏之前（即在 shown.bs.tooltip 或 hidden.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

事件

Event Description
hide.bs.tooltip 当调用 hide 实例方法时，会立即触发该事件。
hidden.bs.tooltip 当工具提示完成对用户的隐藏时（将等待 CSS 过渡完成），将触发此事件。
inserted.bs.tooltip 当工具提示模板添加到 DOM 时，该事件会在 show.bs.tooltip 事件之后触发。
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()