Skip to content
W3S101

bootstrap_ref_js_tooltip

Bootstrap 5 JavaScript [工具提示]（Tooltips）

Section titled “Bootstrap 5 JavaScript [工具提示]（Tooltips）”

工具提示是当用户将鼠标悬停或聚焦到某个元素上时出现的小弹窗，提供上下文信息。Bootstrap 5 工具提示由 [Popper.js] 提供支持，并且需要通过 JavaScript 进行[初始化]（Initialization）。

[主要变化]（Key Change）：Bootstrap 5 不再依赖 [jQuery]。所有 JavaScript 插件，包括工具提示，都是使用[纯 JavaScript]（Vanilla JavaScript）实现的。

通过 data-bs-* 属性启用工具提示

Section titled “通过 data-bs-* 属性启用工具提示”

添加工具提示最简单的方法是在您的 HTML 中直接使用 data-bs-* 属性。data-bs-toggle="tooltip" 会激活工具提示。

title 属性（或用于 HTML 内容的 data-bs-title）指定了要在工具提示内部显示的文本。

<button type="button" class="btn btn-secondary"
        data-bs-toggle="tooltip" data-bs-placement="top"
        title="This is a tooltip!">
  Hover over me
</button>


<!-- 请记住：即使使用了数据属性，工具提示也必须通过 JavaScript 进行初始化才能工作。请参阅下面的“通过 JavaScript 初始化”部分。 -->

通过 JavaScript 初始化工具提示

Section titled “通过 JavaScript 初始化工具提示”

工具提示必须被[显式初始化]（Explicitly Initialized）。您可以选择带有 data-bs-toggle="tooltip" 属性的元素并对其进行初始化。

// 初始化页面上的所有工具提示
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'));
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new bootstrap.Tooltip(tooltipTriggerEl);
});


// 通过 ID 初始化单个工具提示
var myTooltipEl = document.getElementById('mySpecialTooltip');
if (myTooltipEl) {
  var tooltip = new bootstrap.Tooltip(myTooltipEl, {
    // 可选的配置对象
    boundary: 'window' // 示例选项
  });
}


/*
  常见错误：忘记包含此初始化脚本是工具提示不显示的最常见原因。确保此脚本在 DOM 加载后以及包含 Bootstrap 的 JS 文件之后运行。更多详情请参阅：https://getbootstrap.com/docs/5.3/components/tooltips/#enable-tooltips
*/

工具提示选项

Section titled “工具提示选项”

[选项]（Options）可以通过 data-bs-* 属性或 JavaScript 传递。对于数据属性，将选项名称附加到 data-bs- 后面，例如 data-bs-placement="left" 或 data-bs-html="true"。

名称类型默认值描述
animationbooleantrue为工具提示应用 CSS 淡入淡出[过渡效果]（Transition）。
containerstring | false | Elementfalse将工具提示附加到特定元素。示例：container: 'body' 或 data-bs-container="body"。在复杂的[组件]（Components）中，这对于避免渲染问题非常有用。
delaynumber | object0延迟显示和隐藏工具提示（毫秒）。对象结构：delay: { "show": 500, "hide": 100 }。可以通过 data-bs-delay="500"（同时设置）或 data-bs-delay='{"show":500,"hide":100}' 设置。
htmlbooleanfalse允许在工具提示内使用 HTML 标记。如果为 true，请使用 data-bs-title 而不是 title 属性来指定 HTML 内容。示例：data-bs-html="true" data-bs-title="<em>HTML</em> **here**"。安全提示：如果使用此选项，请对用户输入进行[消毒]（Sanitize），以防止 [XSS 攻击]（Cross-Site Scripting）。
placementstring | function’top’如何定位工具提示：auto、top、bottom、left、right。也可以是一个[函数]（Function）。
selectorstring | falsefalse如果提供了[选择器]（Selector），工具提示对象将[委托]（Delegated）给指定的目标。这对于动态添加的内容非常有用。
templatestring（默认 SVG 箭头模板）创建工具提示时使用的基础 HTML。工具提示的 title 将被注入到 .tooltip-inner 中。.tooltip-arrow 将是箭头。
titlestring | Element | function”如果 title 属性或 data-bs-title 不存在时的默认 title 值。对于动态 title，可以是一个函数。
offset[number, number] | string | function[0, 0]工具提示相对于目标的[偏移量]（Offset）。示例：data-bs-offset="10,20"。
triggerstring’hover focus’工具提示如何被[触发]（Triggered）：click、hover、focus、manual。您可以传递多个触发器，用空格分隔。示例：data-bs-trigger="click focus"。

有关选项及其详细解释的完整列表，请访问官方文档：https://getbootstrap.com/docs/5.3/components/tooltips/#options

工具提示方法

Section titled “工具提示方法”

工具提示[实例]（Instances）提供了通过[编程方式]（Programmatically）控制其行为的[方法]（Methods）。

方法描述
bootstrap.Tooltip.getInstance(element)获取与一个 DOM 元素关联的工具提示实例的[静态方法]（Static method）。
bootstrap.Tooltip.getOrCreateInstance(element, [config])获取与一个 DOM 元素关联的工具提示实例的静态方法；如果尚未初始化，则创建一个新的。
show()显示元素的工具提示。myTooltip.show()
hide()隐藏元素的工具提示。myTooltip.hide()
toggle()[切换]（Toggle）元素的工具提示显示/隐藏状态。myTooltip.toggle()
dispose()隐藏并[销毁]（Destroy）元素的工具提示。myTooltip.dispose()
enable()启用元素工具提示的显示能力。myTooltip.enable()
disable()禁用元素工具提示的显示能力。myTooltip.disable()
toggleEnabled()切换元素工具提示的启用/禁用状态。myTooltip.toggleEnabled()
update()[更新]（Update）元素工具提示的位置。myTooltip.update()

使用方法的示例：

var myButton = document.getElementById('myButtonWithTooltip');
var tooltipInstance = bootstrap.Tooltip.getInstance(myButton);
// 或者如果不存在则创建：
// var tooltipInstance = bootstrap.Tooltip.getOrCreateInstance(myButton);


// 以编程方式显示工具提示：
// tooltipInstance.show();

工具提示事件

Section titled “工具提示事件”

Bootstrap 工具提示暴露出几个可以[挂钩]（Hook into）的[事件]（Events）。

事件描述
show.bs.tooltip当调用 show 实例方法时，此事件会立即[触发]（Fire）。
shown.bs.tooltip当工具提示对用户可见时，此事件被触发（会等待 CSS 过渡完成）。
hide.bs.tooltip当调用 hide 实例方法时，此事件会立即触发。
hidden.bs.tooltip当工具提示完全对用户隐藏后，此事件被触发（会等待 CSS 过渡完成）。
inserted.bs.tooltip在 show.bs.tooltip 事件之后、将工具提示模板添加到 DOM 时，此事件被触发。

监听事件的示例：

var myTooltipEl = document.getElementById('exampleTooltip');
if (myTooltipEl) {
  myTooltipEl.addEventListener('shown.bs.tooltip', function () {
    console.log('Tooltip is now fully shown!');
  });
}

使用 CSS 定制工具提示外观

Section titled “使用 CSS 定制工具提示外观”

您可以通过定位 Bootstrap 的工具提示类或使用 CSS 自定义属性（[变量]（Variables））来定制工具提示的外观。Bootstrap 5 广泛使用了 CSS 变量，以便更轻松地进行定制。

/* 示例：使用 CSS 变量定制工具提示的背景色和文本颜色 */
:root {
  --bs-tooltip-bg: #8AC007;
  --bs-tooltip-color: #FFFFFF;
  --bs-tooltip-opacity: 0.95;
  --bs-tooltip-arrow-width: .9rem;
  --bs-tooltip-arrow-height: .45rem;
  --bs-tooltip-padding-x: 1rem;
  --bs-tooltip-padding-y: .5rem;
  --bs-tooltip-font-size: .9rem;
}


/* 如果需要更具体的覆盖： */
.tooltip-inner {
  /* 如果变量不足以满足需求，可以覆盖 Bootstrap 的默认样式 */
  background-color: #007bff; /* 示例：蓝色背景 */
  color: white;
  border-radius: .25rem;
  padding: .5rem 1rem;
}


.tooltip-arrow::before {
  /* 示例：更改箭头颜色以匹配自定义背景 */
  /* border-top-color: #007bff; /* 如果工具提示在上方 */
}


/*
  最佳实践：首先尝试覆盖 CSS 自定义属性。
  参考 Bootstrap 的 _variables.scss（或编译后的 CSS）查看所有可用的工具提示 CSS 变量。
  在这里找到它们：https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss（搜索 'tooltip'）
*/

应用场景：工具提示非常适合用于提供[图标按钮]（Icon Buttons）的提示、解释缩写，或显示被截断内容的完整文本。