工具提示

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

此页面上的内容

概述

使用工具提示插件时需要了解的事项

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

变量

在 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 元素（例如链接或表单控件）来保持工具提示对键盘和辅助技术用户可访问。虽然可以通过添加 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>

选项

由于可以通过数据属性或 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 上给出的值。此外，现有数据属性能够容纳 JSON 值，例如 data-bs-delay='{"show":0,"hide":150}'。

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

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

名称	类型	默认值	说明
`allowList`	对象	默认值	包含允许的属性和标记的对象。
`animation`	布尔值	`true`	对工具提示应用 CSS 淡入淡出过渡。
`boundary`	字符串、元素	`'clippingParents'`	工具提示的溢出约束边界（仅适用于 Popper 的 preventOverflow 修饰符）。默认情况下，它是 `'clippingParents'`，并且可以接受一个 HTMLElement 引用（仅通过 JavaScript）。有关详细信息，请参阅 Popper 的 detectOverflow 文档。
`容器`	字符串、元素、false	`false`	将工具提示附加到特定元素。示例：`container: 'body'`。此选项特别有用，因为它允许您将工具提示定位在触发元素附近的文档流中 - 这将防止工具提示在窗口调整大小时远离触发元素。
`customClass`	字符串、函数	`''`	在显示工具提示时向其添加类。请注意，这些类将添加到模板中指定的任何类中。要添加多个类，请用空格分隔它们：`'class-1 class-2'`。您还可以传递一个函数，该函数应返回一个包含其他类名的单个字符串。
`延迟`	数字、对象	`0`	延迟显示和隐藏工具提示（毫秒） - 不适用于手动触发类型。如果提供数字，则延迟将应用于隐藏/显示。对象结构为：`delay: { "show": 500, "hide": 100 }`。
`fallbackPlacements`	数组	`['top', 'right', 'bottom', 'left']`	通过提供数组中的位置列表（按优先顺序）来定义后备位置。有关详细信息，请参阅 Popper 的行为文档。
`html`	布尔值	`false`	允许工具提示中使用 HTML。如果为 true，则工具提示的 `title` 中的 HTML 标签将在工具提示中呈现。如果为 false，则 `innerText` 属性将用于将内容插入到 DOM 中。如果您担心 XSS 攻击，请使用文本。
`偏移`	数组、字符串、函数	`[0, 0]`	工具提示相对于其目标的偏移。您可以使用逗号分隔的值传递数据属性中的字符串，例如：`data-bs-offset="10,20"`。当使用函数确定偏移量时，它会被调用，其第一个参数是一个包含弹出器位置、引用和弹出器矩形的对象。触发元素 DOM 节点作为第二个参数传递。该函数必须返回一个包含两个数字的数组：滑动、距离。有关详细信息，请参阅 Popper 的偏移文档。
`位置`	字符串、函数	`'top'`	如何定位工具提示：自动、顶部、底部、左侧、右侧。当指定 `auto` 时，它将动态重新定向工具提示。当使用函数确定位置时，它会被调用，其第一个参数是工具提示 DOM 节点，其第二个参数是触发元素 DOM 节点。`this` 上下文被设置为工具提示实例。
`popperConfig`	null、对象、函数	`null`	如需更改 Bootstrap 的默认 Popper 配置，请参阅 Popper 的配置。当使用函数创建 Popper 配置时，它将使用包含 Bootstrap 的默认 Popper 配置的对象进行调用。它可帮助您使用和合并默认配置和您自己的配置。该函数必须返回 Popper 的配置对象。
`sanitize`	布尔值	`true`	启用或禁用清理。如果激活 `'template'`、`'content'` 和 `'title'` 选项将被清理。
`sanitizeFn`	null、函数	`null`	您可以在此处提供您自己的清理函数。如果您更喜欢使用专用库来执行清理，这可能很有用。
`selector`	字符串、false	`false`	如果提供了选择器，将把工具提示对象委托给指定的目标。在实践中，这用于将工具提示应用于动态添加的 DOM 元素（支持 `jQuery.on`）。请参阅此问题和一个信息丰富的示例。注意：不能将 `title` 属性用作选择器。
`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`	字符串、元素、函数	`''`	工具提示标题。如果给定了一个函数，它将使用其 `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`	切换元素的工具提示。在工具提示实际显示或隐藏之前返回给调用方（即在 `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`	当工具提示模板已添加到 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()

工具提示

概述

示例

启用工具提示

链接上的工具提示

自定义工具提示

方向

CSS

变量

Sass 变量

用法

标记

已禁用元素

选项

各个工具提示的数据属性

使用带有 popperConfig 的函数

方法

事件

使用带有 `popperConfig` 的函数