工具提示

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

本页目录

概览

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

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

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

默认情况下，此组件使用内置的内容清理器，它会移除所有未明确允许的 HTML 元素。有关更多详细信息，请参阅我们的 JavaScript 文档中的清理器部分。

此组件的动画效果取决于 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>

在你的 HTML 中可以自由使用 title 或 data-bs-title。当使用 title 时，Popper 会在元素渲染时自动将其替换为 data-bs-title。

自定义工具提示

在 v5.2.0 中添加

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

site/src/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

变量

在 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')
})

标记

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

通过仅将工具提示添加到传统上可通过键盘聚焦和交互的 HTML 元素（例如链接或表单控件）上，确保工具提示对键盘和辅助技术用户可访问。虽然其他 HTML 元素可以通过添加 tabindex="0" 来使其可聚焦，但这可能会在非交互元素上为键盘用户产生令人烦恼和困惑的 tab 停靠点，而且大多数辅助技术在这种情况下目前不会宣布工具提示。此外，不要仅依赖 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>

选项

由于选项可以通过数据属性或 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，且单独的数据属性将覆盖 data-bs-config 上给定的值。此外，现有的数据属性也能够存放如 data-bs-delay='{"show":0,"hide":150}' 的 JSON 值。

最终的配置对象是data-bs-config、data-bs-和js object合并的结果，其中最新提供的键值会覆盖其他键值。

请注意，出于安全原因，sanitize、sanitizeFn和allowList选项不能通过数据属性提供。

名称	类型	默认值	描述
`allowList`	object	默认值	一个包含允许标签和属性的对象。那些未明确允许的将被移除内容净化器. 在向此列表添加内容时要谨慎。参考 OWASP 跨站脚本防护备忘单欲了解更多信息。
`animation`	boolean	`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`	array	`['top', 'right', 'bottom', 'left']`	通过在数组中提供位置列表（按优先顺序）来定义回退位置。更多信息请参考 Popper 的文档。行为文档.
`html`	boolean	`false`	允许在工具提示中使用 HTML。如果为真，工具提示中的 HTML 标签 `title` 将在工具提示中显示。如果为假， `innerText` 该属性将用于将内容插入到 DOM 中。在处理用户生成的输入时，优先使用文本防止 XSS 攻击.
`offset`	数组，字符串，函数	`[0, 6]`	工具提示相对于其目标的偏移量。你可以在数据属性中传递一个以逗号分隔的字符串，例如： `data-bs-offset="10,20"`当使用函数来确定偏移量时，它会以一个包含 popper 位置、参考元素和 popper 矩形的对象作为第一个参数进行调用。触发元素的 DOM 节点作为第二个参数传递。该函数必须返回一个包含两个数字的数组：打滑, 距离. 有关更多信息，请参阅Popper的著作补偿文档.
`placement`	字符串，函数	`'top'`	如何定位工具提示：自动、上、下、左、右。当 `auto` 如果指定，它将动态重新定位工具提示。当使用函数来确定位置时，该函数的第一个参数是工具提示的 DOM 节点，第二个参数是触发元素的 DOM 节点。 `this` 上下文已设置为工具提示实例。
`popperConfig`	null，对象，函数	`null`	要更改 Bootstrap 的默认 Popper 配置，请参阅 Popper的配置当使用函数来创建 Popper 配置时，它会被一个包含 Bootstrap 默认 Popper 配置的对象调用。它帮助你使用并合并默认配置与自己的配置。该函数必须返回一个 Popper 的配置对象。
`sanitize`	boolean	`true`	启用内容净化. 如果是真的， `template`, `content` 和 `title` 选项将被清理。在禁用内容清理时要谨慎。参考 OWASP 跨站脚本防护备忘单欲了解更多信息。仅因禁用内容清理而导致的漏洞不被视为 Bootstrap 安全模型的范围内。
`sanitizeFn`	空值，函数	`null`	提供一个替代方案内容净化功能。如果你更喜欢使用专用库来执行清理，这可能会很有用。
`selector`	字符串，假	`false`	如果提供了选择器，工具提示对象将委托给指定的目标。在实际操作中，这也用于将工具提示应用于动态添加的 DOM 元素（`jQuery.on` 支持)。参见这个问题. 注意: `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`	字符串，元素，函数	`''`	工具提示标题。如果提供了一个函数，将使用它调用 `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 文档中了解更多信息。

方法	描述
`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

事件

事件	描述
`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()

工具提示

概览

示例

启用工具提示

链接上的工具提示

自定义工具提示

方向

CSS

变量

Sass 变量

用法

标记

禁用的元素

选项

单个工具提示的数据属性

在 popperConfig 上使用函数

方法

事件

在 `popperConfig` 上使用函数