Tooltips提示

使用 CSS3 为动画添加自定义 Bootstrap Tooltips的文档和示例，为本地标题存储使用 data-bs-attributes。

在此页

概述

使用Tooltips插件时的注意事项：

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

明白了吗？太好了，让我们看看它们如何使用一些示例。

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

该组件的动画效果依赖于prefers-reduced-motion媒体查询。请参阅我们的辅助功能文档的减少运动部分。

例子

启用Tooltips

如上所述，您必须先初始化Tooltips，然后才能使用它们。初始化页面上所有Tooltips的一种方法是通过它们的data-bs-toggle属性选择它们，如下所示：

const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl))

链接上的Tooltips

将鼠标悬停在下面的链接上以查看Tooltips：

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>

随意使用title或data-bs-title在您的 HTML 中。当使用title时，Popper会在渲染元素时自动用data-bs-title替换它。

自定义Tooltips

添加于 v5.2.0

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

.custom-tooltip {
  --bs-tooltip-bg: var(--bs-primary);
}

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>

方向

将鼠标悬停在下方的按钮上可查看Tooltips的四个方向：顶部、右侧、底部和左侧。在 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 变量方法的一部分，Tooltips现在使用本地 CSS 变量.tooltip来增强实时自定义。CSS 变量的值是通过 Sass 设置的，因此仍然支持 Sass 自定义。

  --#{$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 变量

$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

用法

Tooltips插件按需生成内容和标记，默认情况下将Tooltips放在触发元素之后。

通过 JavaScript 触发Tooltips：

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

溢出`auto`和`scroll`

当父容器具有overflow: auto或overflow: scroll时，Tooltips位置会尝试自动更改.table-responsive，但仍保持原始位置的定位。要解决此问题，请将boundary选项（对于使用选项的翻转修饰符popperConfig）设置为任何 HTMLElement 以覆盖默认值'clippingParents'，例如document.body：

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

标记

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

使Tooltips适用于键盘和辅助技术用户

您应该只将Tooltips添加到传统上可通过键盘聚焦和交互的 HTML 元素（例如链接或表单控件）。虽然可以通过添加该属性使任意 HTML 元素（例如<span>s）成为可聚焦的tabindex="0"，但这会为键盘用户在非交互元素上添加潜在的烦人和混乱的制表位，并且大多数辅助技术目前不会在这种情况下公布Tooltips。此外，不要仅仅依赖于hover作为Tooltips的触发器，因为这将使您的Tooltips无法为键盘用户触发。

<!-- 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-top" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

禁用元素

具有disabled属性的元素是不可交互的，这意味着用户无法聚焦、悬停或单击它们来触发Tooltips（或弹出窗口）。作为一种解决方法，您需要从包装器中触发Tooltips，<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}'.

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

名称	类型	默认	描述
`allowList`	object	默认值	包含允许的属性和标签的对象。
`animation`	boolean	`true`	将 CSS 淡入淡出过渡应用于Tooltips。
`boundary`	string, element	`'clippingParents'`	Tooltips的溢出约束边界（仅适用于 Popper 的 preventOverflow 修饰符）。默认情况下，它`'clippingParents'`可以接受 HTMLElement 引用（仅通过 JavaScript）。有关详细信息，请参阅 Popper 的detectOverflow 文档。
`container`	string, element, false	`false`	将Tooltips附加到特定元素。例子：`container: 'body'`。此选项特别有用，因为它允许您将Tooltips放置在触发元素附近的文档流中 - 这将防止Tooltips在窗口调整大小时漂离触发元素。
`customClass`	string, function	`''`	显示时将类添加到Tooltips。请注意，除了模板中指定的任何类之外，还将添加这些类。要添加多个类，请用空格分隔它们：`'class-1 class-2'`。您还可以传递一个函数，该函数应返回包含其他类名的单个字符串。
`delay`	number, object	`0`	延迟显示和隐藏Tooltips（毫秒）—不适用于手动触发类型。如果提供了数字，延迟将应用于隐藏/显示。对象结构是：`delay: { "show": 500, "hide": 100 }`.
`fallbackPlacements`	array	`['top', 'right', 'bottom', 'left']`	通过提供数组中的展示位置列表（按优先顺序）来定义后备展示位置。有关更多信息，请参阅 Popper 的行为文档。
`html`	boolean	`false`	在Tooltips中允许 HTML。如果为真，Tooltips中的 HTML 标记`title`将在Tooltips中呈现。如果为 false，`innerText`属性将用于将内容插入 DOM。如果您担心 XSS 攻击，请使用文本。
`offset`	array, string, function	`[0, 0]`	Tooltips相对于其目标的偏移量。您可以使用逗号分隔值在数据属性中传递一个字符串，例如：`data-bs-offset="10,20"`。当一个函数被用来确定偏移量时，它被调用时带有一个包含 popper 位置、引用和 popper rects 的对象作为它的第一个参数。触发元素 DOM 节点作为第二个参数传递。该函数必须返回一个包含两个数字的数组：skidding和distance。有关更多信息，请参阅 Popper 的偏移量文档。
`placement`	string, function	`'top'`	如何定位Tooltips：自动、顶部、底部、左侧、右侧。指定时`auto`，它将动态重新定向Tooltips。当一个函数被用来确定位置时，它被调用，Tooltips DOM 节点作为它的第一个参数，触发元素 DOM 节点作为它的第二个参数。`this`上下文设置为Tooltips实例。
`popperConfig`	null, object, function	`null`	要更改 Bootstrap 的默认 Popper 配置，请参阅Popper 的配置。当一个函数被用来创建 Popper 配置时，它被调用一个包含 Bootstrap 默认 Popper 配置的对象。它可以帮助您使用默认设置并将其与您自己的配置合并。该函数必须返回 Popper 的配置对象。
`sanitize`	boolean	`true`	启用或禁用清理。如果激活`'template'`，选项将被清除`'content'`。`'title'`
`sanitizeFn`	null, function	`null`	在这里您可以提供自己的清理功能。如果您更喜欢使用专用库来执行清理，这会很有用。
`selector`	string, false	`false`	如果提供了选择器，Tooltips对象将被委托给指定的目标。实际上，这也用于将Tooltips应用于动态添加的 DOM 元素（`jQuery.on`支持）。请参阅此问题和一个信息示例。注意：`title`属性不得用作选择器。
`template`	string	`'<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'`	创建Tooltips时要使用的基本 HTML。Tooltips`title`将被注入到`.tooltip-inner`. `.tooltip-arrow`将成为Tooltips的箭头。最外面的包装元素应该有`.tooltip`类和`role="tooltip"`。
`title`	string, element, function	`''`	`title`如果属性不存在，则为默认标题值。如果给出了一个函数，它将被调用，其`this`引用设置为弹出窗口附加到的元素。
`trigger`	string	`'hover focus'`	如何触发Tooltips：单击、悬停、聚焦、手动。您可以传递多个触发器；用空格分隔它们。`'manual'`指示Tooltips将通过`.tooltip('show')`,`.tooltip('hide')`和`.tooltip('toggle')`方法以编程方式触发；此值不能与任何其他触发器结合使用。`'hover'`单独将导致无法通过键盘触发的Tooltips，并且只有在存在为键盘用户传达相同信息的替代方法时才应使用。

单个Tooltips的数据属性

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

使用函数`popperConfig`

const tooltip = new bootstrap.Tooltip(element, {
  popperConfig(defaultBsPopperConfig) {
    // const newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

方法

异步方法和转换

所有 API 方法都是异步的并开始转换。它们会在转换开始但结束之前立即返回给调用者。此外，将忽略对转换组件的方法调用。

有关详细信息，请参阅我们的 JavaScript 文档。

方法	描述
`disable`	删除显示元素Tooltips的能力。Tooltips只有在重新启用后才能显示。
`dispose`	隐藏和销毁元素的Tooltips（删除 DOM 元素上存储的数据）。使用委托（使用选项创建）的`selector`Tooltips不能在后代触发元素上单独销毁。
`enable`	使元素的Tooltips能够显示。默认情况下启用Tooltips。
`getInstance`	允许您获取与 DOM 元素关联的Tooltips实例的静态方法，或者创建一个新的实例以防未初始化。
`getOrCreateInstance`	允许您获取与 DOM 元素关联的Tooltips实例的静态方法，或者创建一个新的实例以防未初始化。
`hide`	隐藏元素的Tooltips。在Tooltips实际上被隐藏之前返回给调用者（即在`hidden.bs.tooltip`事件发生之前）。这被认为是Tooltips的“手动”触发。
`setContent`	提供一种在Tooltips初始化后更改其内容的方法。
`show`	显示元素的Tooltips。在Tooltips实际显示之前（即事件发生之前）返回给调用者。`shown.bs.tooltip`这被认为是Tooltips的“手动”触发。永远不会显示带有零长度标题的Tooltips。
`toggle`	切换元素的Tooltips。在Tooltips实际显示或隐藏之前返回给调用者（即在`shown.bs.tooltip`或`hidden.bs.tooltip`事件发生之前）。这被认为是Tooltips的“手动”触发。
`toggleEnabled`	切换显示或隐藏元素Tooltips的能力。
`update`	更新元素Tooltips的位置。

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`当Tooltips模板已添加到 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()

Tooltips提示

概述

例子

启用Tooltips

链接上的Tooltips

自定义Tooltips

方向

CSS

变量

Sass 变量

用法

溢出auto和scroll

标记

使Tooltips适用于键盘和辅助技术用户

禁用元素

选项

单个Tooltips的数据属性

使用函数popperConfig

方法

异步方法和转换

事件

溢出`auto`和`scroll`

使用函数`popperConfig`