工具提示

概览

将鼠标悬停在下面的按钮上以查看工具提示。默认情况下，工具提示会出现在其触发元素（带有 data-bs-toggle="tooltip" 属性的任何元素）上方。

HTML

<button type="button" class="btn-solid theme-primary"
        data-bs-toggle="tooltip"
        data-bs-title="Tooltip on top">
  Example tooltip
</button>

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

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

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

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

此组件的动画效果取决于 prefers-reduced-motion 媒体查询。请参阅我们无障碍文档中的减少动画部分。

示例

链接上的工具提示

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

HTML

<p class="fg-3">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 时，Floating UI 会在元素渲染时自动将其替换为 data-bs-title。

自定义工具提示

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

node_modules/@twbs/bui/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-solid theme-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>

职位安排

设置 data-bs-placement 来改变方向。将鼠标悬停在下面的按钮上以查看四个提示方向：顶部、右侧、底部和左侧。在使用 RTL 的 Bootstrap 时，方向会镜像显示。

HTML

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

响应式放置

使用响应前缀在不同断点更改位置。语法是 breakpoint:placement，其中断点是 sm、md、lg、xl 或 2xl 之一。

HTML

<button type="button" class="btn-solid theme-secondary"
        data-bs-toggle="tooltip"
        data-bs-placement="top md:right lg:bottom"
        data-bs-title="Responsive tooltip">
  Top → md:right → lg:bottom
</button>
<button type="button" class="btn-solid theme-secondary"
        data-bs-toggle="tooltip"
        data-bs-placement="left lg:top"
        data-bs-title="Responsive tooltip">
  Left → lg:top
</button>

调整浏览器大小以查看在不同断点处工具提示位置的变化。

自定义 HTML

并添加了自定义 HTML：

HTML

<button type="button" class="btn-solid theme-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：

HTML

<a href="#" class="d-inline-block"
        data-bs-toggle="tooltip"
        data-bs-title="Default tooltip"
        aria-label="Hover or focus to see default tooltip">
  <svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 100 100" aria-hidden="true">
    <rect width="100%" height="100%" fill="#563d7c"/>
    <circle cx="50" cy="50" r="30" fill="#007bff"/>
  </svg>
</a>

交互式工具提示

将指针移动到提示的顶部以访问其中的交互内容，例如链接。当指针位于触发器或提示上方时，工具提示会保持打开状态。当指针离开两者或按下Escape键时，它会隐藏。这有助于满足WCAG 1.4.13 “悬停或聚焦时的内容” 成功标准。

HTML

<button type="button" class="btn-solid theme-primary"
        data-bs-toggle="tooltip"
        data-bs-html="true"
        data-bs-title="Read the <a href='https://bs.88fc.cn/'>full docs</a> for more.">
  Hover, then move onto the tip
</button>

禁用的元素

带有 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-solid theme-primary" type="button" disabled>Disabled button</button>
</span>

CSS

变量

工具提示在.tooltip上使用本地 CSS 变量进行实时自定义。CSS 变量的值是从每个组件独有的 Sass map生成，并应用于上述类。

scss/_tooltip.scss

// stylelint-disable-next-line scss/dollar-variable-default
$tooltip-tokens: defaults(
  (
    --tooltip-zindex: var(--z-tooltip),
    --tooltip-max-width: 200px,
    --tooltip-padding-x: var(--spacer-3),
    --tooltip-padding-y: calc(var(--spacer) * .375),
    --tooltip-font-size: var(--font-size-sm),
    --tooltip-color: var(--bg-body),
    --tooltip-bg: var(--fg-body),
    --tooltip-border-radius: var(--radius-5),
    --tooltip-opacity: .95,
    --tooltip-arrow-width: .8rem,
    --tooltip-arrow-height: .4rem,
    --tooltip-transition-property: "opacity",
    --tooltip-transition-duration: .15s,
    --tooltip-transition-timing: linear,
  ),
  $tooltip-tokens
);

用法

工具提示插件按需生成内容和标记，并且默认将工具提示放置在其触发元素之后。通过 JavaScript 触发工具提示：

JavaScript

          const exampleEl = document.getElementById('example')
const tooltip = new bootstrap.Tooltip(exampleEl, options)

当父容器具有时，工具提示会自动尝试更改位置 overflow: auto 或 overflow: scroll，但仍保持原位置的定位。设置 boundary 选项（用于 shift 中间件使用的 floatingConfig 选项）适用于任何 HTMLElement，以覆盖默认值， 'clippingParents'例如 document.body:

JavaScript

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

委托提示

要一次在多个触发器上启用工具提示——包括后来添加到 DOM 的元素——可以在父元素上初始化一个实例，并传入 selector 选项。任何匹配的子元素都会获得工具提示而无需重新初始化：

JavaScript

          const tooltip = new bootstrap.Tooltip(document.body, {
  selector: '[data-bs-toggle="tooltip"]'
})

通过数据属性

属性	描述
`data-bs-toggle="tooltip"`	在触发元素上初始化工具提示。
`data-bs-title`	在工具提示主体中显示的文本（或允许时的 HTML）。
`data-bs-placement`	工具提示的放置位置（`top`、`right`、`bottom`、`left` 或响应式变体）。
`data-bs-custom-class`	添加到工具提示的额外类名，用于主题化。
`data-bs-html`	当 `true`时，允许标题中使用 HTML（请谨慎使用；用户内容建议使用纯文本）。

标记

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

通过仅将工具提示添加到传统上可通过键盘聚焦和交互的 HTML 元素（例如链接或表单控件）来确保其对键盘和辅助技术用户可访问。虽然通过添加 tabindex="0" 可以使其他 HTML 元素可聚焦，但这可能会在非交互元素上为键盘用户创建令人恼火和混乱的标签停靠点，而且大多数辅助技术目前不会在这种情况下朗读工具提示。此外，不要仅依靠 hover 作为工具提示的触发方式，因为这会使键盘用户无法触发它们。

显示的工具提示可以通过按 Escape 键来关闭，有助于满足 WCAG 1.4.13 “悬停或焦点上的内容” 成功标准。当指针移到提示上时，工具提示也会保持打开状态，因此用户可以访问其中的交互内容。与下拉菜单一样，在对话框中显示的工具提示会自行关闭：第一次按 Escape 关闭工具提示，再次按则关闭对话框。

HTML

          <!-- 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>

依赖项

如果你从源代码构建 Bootstrap 的 JS，tooltip 插件需要以下 JavaScript 文件：

文件	描述
`js/src/tooltip.ts`	主提示组件
`js/src/base-component.ts`	基础组件类
`js/src/dom/data.ts`	元素数据存储
`js/src/dom/event-handler.ts`	事件处理工具
`js/src/dom/manipulator.ts`	数据属性操作
`js/src/dom/selector-engine.ts`	DOM选择器工具
`js/src/util/config.ts`	配置基类
`js/src/util/floating-ui.ts`	响应式布局工具
`js/src/util/index.ts`	核心实用功能
`js/src/util/sanitizer.ts`	HTML 内容净化器
`js/src/util/template-factory.ts`	模板渲染工具
`@floating-ui/dom`	第三方定位库

选项

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

所有组件都支持一个保留的数据属性 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 渐隐过渡。将其设置为 `false` 添加 `.tooltip-instant` 到顶端，会关闭淡出效果。
`boundary`	字符串，元素	`'clippingParents'`	工具提示的溢出约束边界（仅适用于 Floating UI 的 shift 中间件）。默认情况下，它是 `'clippingParents'` 并且可以接受一个 HTMLElement 引用（仅通过 JavaScript）。有关更多信息，请参阅 Floating UI 的交接文件.
`container`	字符串，元素，假	`false`	将工具提示附加到特定元素。示例： `container: 'body'`这个选项特别有用，因为它允许你将工具提示定位在文档流中触发元素附近 —— 这可以防止在窗口调整大小时工具提示偏离触发元素。
`customClass`	字符串，函数	`''`	在显示工具提示时添加类。请注意，这些类将会在模板中指定的任何类之外附加添加。要添加多个类，请用空格分隔它们： `'class-1 class-2'`你也可以传入一个函数，该函数应返回一个包含额外类名的单一字符串。
`delay`	数字, 对象	`0`	延迟显示和隐藏工具提示（毫秒）——不适用于手动触发类型。如果提供数字，延迟将同时应用于隐藏和显示。对象结构如下： `delay: { "show": 500, "hide": 100 }`.
`fallbackPlacements`	array	`['top', 'right', 'bottom', 'left']`	通过在数组中提供位置列表（按优先顺序）来定义备用位置。有关更多信息，请参阅 Floating UI 的文档翻转文档.
`html`	boolean	`false`	允许在工具提示中使用 HTML。如果为真，工具提示中的 HTML 标签 `title` 将在工具提示中显示。如果为假, `innerText` 该属性将用于将内容插入到 DOM 中。在处理用户生成的输入时，优先使用文本防止 XSS 攻击.
`offset`	数组，字符串，函数	`[0, 6]`	工具提示相对于其目标的偏移量。你可以在数据属性中传递一个以逗号分隔的字符串，例如： `data-bs-offset="10,20"`当使用函数来确定偏移量时，它会以包含浮动位置、参考元素和浮动矩形的对象作为第一个参数调用。触发元素的 DOM 节点作为第二个参数传入。该函数必须返回一个包含两个数字的数组：交叉轴, 主轴. 有关更多信息，请参阅 Floating UI 的补偿文档.
`placement`	字符串，函数	`'top'`	如何定位工具提示：顶部、底部、左侧、右侧。支持响应式前缀，如 `'top md:right lg:bottom'` 在不同的断点更改位置。当使用函数来确定位置时，它会以提示信息的 DOM 节点作为第一个参数，以触发元素的 DOM 节点作为第二个参数进行调用。
`floatingConfig`	null，对象，函数	`null`	要更改 Bootstrap 的默认 Floating UI 配置，请参阅 Floating UI 的配置当使用函数来创建 Floating UI 配置时，它会被一个包含 Bootstrap 默认 Floating UI 配置的对象调用。它帮助你使用并合并默认配置与自己的配置。该函数必须返回一个用于 Floating UI 的配置对象。
`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'` 单独使用会导致无法通过键盘触发工具提示，只有在为键盘用户提供传达相同信息的替代方法时才应使用。

单个工具提示的数据属性

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

使用带有 `floatingConfig` 的函数

JavaScript

          const tooltip = new bootstrap.Tooltip(element, {
  floatingConfig(defaultBsFloatingConfig) {
    // const newFloatingConfig = {...}
    // use defaultBsFloatingConfig if needed...
    // return newFloatingConfig
  }
})

方法

显示或隐藏组件的方法会返回一个 Promise。 当过渡结束时，该 Promise 会被解析，所以 await 会在 shown.bs.* 或 hidden.bs.* 监听器运行的同一时刻继续。方法仍会立即返回，并且永远不会阻塞调用者。对已在过渡中的组件进行调用不会有任何效果，并会立即解析。在我们的 JavaScript 文档中了解更多。

方法	描述
`disable`	移除元素显示工具提示的能力。只有在重新启用后，工具提示才能显示。
`dispose`	隐藏并销毁元素的工具提示（删除 DOM 元素上的存储数据）。使用委托的工具提示（通过创建的方式）这 `selector` 选项) 不能在后代触发元素上单独销毁。
`enable`	赋予元素显示工具提示的能力。工具提示默认启用。
`getInstance`	静态一种方法，允许你获取与 DOM 元素关联的提示信息实例。
`getOrCreateInstance`	静态该方法允许你获取与 DOM 元素关联的工具提示实例，或者在未初始化时创建一个新的实例。
`hide`	隐藏元素的工具提示。返回一个在工具提示隐藏后解决的承诺（即在……之后 `hidden.bs.tooltip` 事件触发）。这被视为工具提示的“手动”触发。
`setContent`	提供了一种在工具提示初始化后更改其内容的方法。
`show`	显示元素的工具提示。返回一个在工具提示显示后解决的承诺（即在……之后 `shown.bs.tooltip` 事件触发）。这被认为是“手动”触发工具提示。标题长度为零的工具提示从不显示。
`toggle`	切换元素的工具提示。返回一个在工具提示显示或隐藏后解析的 Promise （即在……之后 `shown.bs.tooltip` 或 `hidden.bs.tooltip` 事件触发）。这被视为工具提示的“手动”触发。
`toggleEnabled`	切换元素工具提示显示或隐藏的功能。
`update`	更新元素工具提示的位置。

JavaScript

          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 过渡完成）会触发此事件。

JavaScript

          const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

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

tooltip.hide()

概览

示例

链接上的工具提示

自定义工具提示

职位安排

响应式放置

自定义 HTML

交互式工具提示

禁用的元素

CSS

变量

用法

委托提示

通过数据属性

标记

依赖项

选项

单个工具提示的数据属性

使用带有 floatingConfig 的函数

方法

事件

使用带有 `floatingConfig` 的函数