工具提示

概述

¥Overview

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

¥Things to know when using the tooltip plugin:

• Tooltips 依赖第三方库 Popper 进行定位。你必须在 bootstrap.js 之前包含 popper.min.js，或者使用包含 Popper 的 bootstrap.bundle.min.js。

  ¥Tooltips rely on the third party library Popper for positioning. You must include popper.min.js before bootstrap.js, or use one bootstrap.bundle.min.js which contains Popper.

• 出于性能原因，工具提示是可选的，因此你必须自行初始化它们。

  ¥Tooltips are opt-in for performance reasons, so you must initialize them yourself.

• 标题长度为零的工具提示永远不会显示。

  ¥Tooltips with zero-length titles are never displayed.

• 指定 container: 'body' 以避免更复杂的组件（例如我们的输入组、按钮组等）中出现渲染问题。

  ¥Specify container: 'body' to avoid rendering problems in more complex components (like our input groups, button groups, etc).

• 在隐藏元素上触发工具提示将不起作用。

  ¥Triggering tooltips on hidden elements will not work.

• .disabled 或 disabled 元素的工具提示必须在封装元素上触发。

  ¥Tooltips for .disabled or disabled elements must be triggered on a wrapper element.

• 当从跨多行的超链接触发时，工具提示将居中。在 <a> 上使用 white-space: nowrap; 可以避免这种行为。

  ¥When triggered from hyperlinks that span multiple lines, tooltips will be centered. Use white-space: nowrap; on your <a>s to avoid this behavior.

• 在从 DOM 中删除相应的元素之前，必须隐藏工具提示。

  ¥Tooltips must be hidden before their corresponding elements have been removed from the DOM.

• 由于 Shadow DOM 内的元素，可以触发工具提示。

  ¥Tooltips can be triggered thanks to an element inside a shadow DOM.

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

¥Got all that? Great, let’s see how they work with some examples.

示例

¥Examples

启用工具提示

¥Enable tooltips

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

¥As mentioned above, you must initialize tooltips before they can be used. One way to initialize all tooltips on a page would be to select them by their data-bs-toggle attribute, like so:

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

链接上的工具提示

¥Tooltips on links

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

¥Hover over the links below to see tooltips:

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

自定义工具提示

¥Custom tooltips

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

¥You can customize the appearance of tooltips using CSS variables. We set a custom class with data-bs-custom-class="custom-tooltip" to scope our custom appearance and use it to override a local CSS variable.

.custom-tooltip {
  --bs-tooltip-bg: var(--bd-violet-bg);
  --bs-tooltip-color: var(--bs-white);
}

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

方向

¥Directions

将鼠标悬停在下面的按钮上可查看四个工具提示方向：上、右、下、左。在 RTL 中使用 Bootstrap 时，方向会被镜像。

¥Hover over the buttons below to see the four tooltips directions: top, right, bottom, and left. Directions are mirrored when using Bootstrap in RTL.

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

¥And with custom HTML added:

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

¥With an SVG:

CSS

变量

¥Variables

作为 Bootstrap 不断发展的 CSS 变量方法的一部分，工具提示现在使用 .tooltip 上的本地 CSS 变量来增强实时自定义。CSS 变量的值是通过 Sass 设置的，因此仍然支持 Sass 自定义。

¥As part of Bootstrap’s evolving CSS variables approach, tooltips now use local CSS variables on .tooltip for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

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

¥Sass variables

$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

用法

¥Usage

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

¥The tooltip plugin generates content and markup on demand, and by default places tooltips after their trigger element. Trigger the tooltip via JavaScript:

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

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

标记

¥Markup

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

¥The required markup for a tooltip is only a data attribute and title on the HTML element you wish to have a tooltip. The generated markup of a tooltip is rather simple, though it does require a position (by default, set to top by the plugin).

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

带有 disabled 属性的元素不具有交互性，这意味着用户无法聚焦、悬停或点击它们来触发工具提示（或弹出窗口）。作为一种解决方法，你需要从封装器 <div> 或 <span> 触发工具提示，理想情况下，使用 tabindex="0" 使其可键盘对焦。

¥Elements with the disabled attribute aren’t interactive, meaning users cannot focus, hover, or click them to trigger a tooltip (or popover). As a workaround, you’ll want to trigger the tooltip from a wrapper <div> or <span>, ideally made keyboard-focusable using tabindex="0".

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

选项

¥Options

As options can be passed via data attributes or JavaScript, you can append an option name to data-bs-, as in data-bs-animation="{value}". Make sure to change the case type of the option name from “camelCase” to “kebab-case” when passing the options via data attributes. For example, use data-bs-custom-class="beautifier" instead of data-bs-customClass="beautifier".

As of Bootstrap 5.2.0, all components support an experimental reserved data attribute data-bs-config that can house simple component configuration as a JSON string. When an element has data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456 and the separate data attributes will override values given on data-bs-config. In addition, existing data attributes are able to house JSON values like data-bs-delay='{"show":0,"hide":150}'.

The final configuration object is the merged result of data-bs-config, data-bs-, and js object where the latest given key-value overrides the others.

将函数与 popperConfig 一起使用

¥Using function with popperConfig

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

方法

¥Methods

const tooltip = bootstrap.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })

活动

¥Events

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

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

tooltip.hide()