跳至主要内容 跳至文档导航
在 GitHub 上查看

工具提示

使用 CSS 和 JavaScript 添加自定义Bootstrap程序工具提示的文档和示例，使用 CSS3 进行动画处理，为本地标题存储添加数据 bs 属性。

当前页

概述

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

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

知道这些了吗？太好了，让我们看看它们是如何用一些例子工作的。

默认情况下，此组件使用内置内容清理器，该清理程序会去除未明确允许的任何 HTML 元素。请参阅我们的 JavaScript 文档中的 sanitizer 部分 了解更多详情。
此组件的动画效果取决于prefers-reduced-motion媒体查询。请参阅我们的辅助功能文档的 减少运动部分。

示例

启用工具提示

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

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

链接上的工具提示

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

Placeholder text to demonstrate some inline links with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of real text. 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 these tooltips on links can work in practice, once you use them on your own site or project.

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。

自定义工具提示

Added in v5.2.0

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

site/assets/scss/_component-examples.scss 
.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>

方向

将鼠标悬停在下面的按钮上可查看四个工具提示方向：顶部、右侧、底部和左侧。在 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

变量

Added in 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选项的翻转修饰符）设置为任何 HTML 环境以覆盖默认值'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-top" 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}'。

请注意，出于安全原因，无法使用数据属性提供sanitize、sanitizeFn和allowList选项。
名称 类型 默认值 描述
allowList object Default value 包含允许的属性和标记的对象。
animation boolean true 将 CSS 淡入淡出过渡应用于工具提示。
boundary string, element 'clippingParents' 工具提示的溢出约束边界（仅适用于 Popper 的 prevent溢出修饰符）。默认情况下，它是'clippingParents'，可以接受 HTMLElement 引用（仅通过 JavaScript）。有关更多信息，请参阅 Popper 的 detectOverflow docs。
container string, element, false false 将工具提示追加到特定元素。示例：container: 'body'。此选项特别有用，因为它允许您将工具提示放置在文档流中靠近触发元素的位置 - 这将防止工具提示在窗口调整大小期间从触发元素上浮动。
customClass string, function '' 在显示工具提示时向其添加类。请注意，除了模板中指定的任何类之外，还将添加这些类。要添加多个类，请用空格分隔它们：'class-1 class-2'。还可以传递一个函数，该函数应返回包含其他类名的单个字符串。
delay number, object 0 延迟显示和隐藏工具提示 （毫秒） - 不适用于手动触发器类型。如果提供了数字，则会对隐藏/显示应用延迟。对象结构为： delay: { "show": 500, "hide": 100 }。
fallbackPlacements array ['top', 'right', 'bottom', 'left'] 通过提供数组中的展示位置列表（按优先顺序）来定义回退展示位置。有关更多信息，请参阅 Popper 的 行为文档。
html boolean false 在工具提示中允许 HTML。如果为 true，则工具提示 title中的 HTML 标记将在工具提示中呈现。如果为 false，则innerText属性将用于将内容插入到 DOM 中。 如果您担心 XSS 攻击，请使用文本。
offset array, string, function [0, 0] 工具提示相对于其目标的偏移量。您可以在数据属性中传递带有逗号分隔值的字符串，例如： data-bs-offset="10,20"。当函数用于确定偏移量时，将使用包含波普尔位置、引用和popper矩形的对象作为其第一个参数来调用该函数。触发元素 DOM 节点作为第二个参数传递。该函数必须返回一个包含两个数字的数组：skiding、distance。有关更多信息，请参阅 Popper 的 偏移文档。
placement string, function 'top' 如何定位工具提示：自动、顶部、底部、左侧、右侧。指定auto时，它将动态地重新定向工具提示。当函数用于确定放置时，使用工具提示 DOM 节点作为其第一个参数，并使用触发元素 DOM 节点作为其第二个参数来调用它。 this上下文设置为工具提示实例。
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 如果提供了选择器，则工具提示对象将委派给指定的目标。在实践中，这也用于将工具提示应用于动态添加的 DOM 元素（jQuery.on支持）。请参阅 this issue 和 a informatative example。 注意：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 string, element, function '' 默认标题值（如果 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

Events

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