工具提示

概述

🌐 Overview

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

🌐 Things to know when using the tooltip plugin:

• 工具提示依赖第三方库 Popper 来定位。你必须在 bootstrap.js 之前包含 popper.min.js，或者使用包含 Popper 的 bootstrap.bundle.min.js。
• 出于性能原因，工具提示是可选择加入的，因此你必须自己初始化它们。
• 标题长度为零的工具提示永远不会显示。
• 指定 container: 'body' 以避免在更复杂的组件（如我们的输入组、按钮组等）中出现渲染问题。
• 在隐藏元素上触发工具提示将不起作用。
• .disabled 或 disabled 元素的工具提示必须在封装元素上触发。
• 当从跨多行的超链接触发时，工具提示将会居中。请在你的 <a> 上使用 white-space: nowrap; 以避免此行为。
• 在从 DOM 中删除相应的元素之前，必须隐藏工具提示。
• 由于 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="默认工具提示">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
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" data-bs-title="右侧提示">
  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
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" data-bs-title="左侧提示">
  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>工具提示</em> <u>与</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="一些工具提示文本！">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()