Bootstrap V5.3 : Tooltips 工具提示中文翻译版

使用 CSS3 用于动画和 data-bs-attributes 用于本地标题存储，使用 CSS 和 JavaScript 添加自定义 Bootstrap 工具提示的文档和示例。

概述

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

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

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

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

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

例子

启用工具提示

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

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

链接上的工具提示

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

[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 中使用或。使用时，Popper 将自动替换为元素渲染时。titledata-bs-titletitledata-bs-title

自定义工具提示

在 v5.2.0 中添加

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

site/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 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系统

变量

在 v5.2.0 中添加

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

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)

当父容器具有或时，工具提示会自动尝试更改位置，但仍保留原始放置的位置。将边界选项（对于使用该选项的翻转修饰符）设置为任何 HTMLElement 以覆盖默认值，例如：overflow: autooverflow: scrollpopperConfig'clippingParents'document.body

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

标记

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

通过仅将工具提示添加到传统上键盘可聚焦和交互的 HTML 元素（例如链接或窗体控件）中，使键盘和辅助技术用户能够访问工具提示。虽然其他 HTML 元素可以通过添加来使可聚焦，但这可能会在键盘用户的非交互式元素上创建烦人且令人困惑的制表位，并且大多数辅助技术目前不会在这种情况下宣布工具提示。此外，不要仅仅依赖作为工具提示的触发器，因为这将使键盘用户无法触发它们。tabindex="0"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-auto" 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 传递，因此您可以将选项名称附加到，如。通过数据属性传递选项时，请确保将选项名称的大小写类型从“camelCase”更改为“kebab-case”。例如，使用代替。data-bs-data-bs-animation="{value}"data-bs-custom-class="beautifier"data-bs-customClass="beautifier"

从 Bootstrap 5.2.0 开始，所有组件都支持实验性保留数据属性，该属性可以将简单的组件配置作为 JSON 字符串容纳。当元素具有和属性时，最终值将是，并且单独的数据属性将覆盖上给出的值。此外，现有数据属性能够容纳 JSON 值，例如 .data-bs-configdata-bs-config='{"delay":0, "title":123}'data-bs-title="456"title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

最终配置对象是、的合并结果，其中最新给定的键值覆盖其他键值。data-bs-configdata-bs-js object

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

名字	类型	违约	描述
`allowList`	对象	默认值	包含允许的标记和属性的对象。未明确允许的内容将被内容清理器删除。添加到此列表时要小心。有关详细信息，请参阅 OWASP 的跨站点脚本预防备忘单。
`animation`	布尔	`true`	将 CSS 淡入淡出过渡应用于工具提示。
`boundary`	字符串，元素	`'clippingParents'`	工具提示的溢出约束边界（仅适用于 Popper 的 preventOverflow 修饰符）。默认情况下，它可以接受 HTMLElement 引用（仅通过 JavaScript）。有关更多信息，请参阅 Popper 的 detectOverflow 文档。`'clippingParents'`
`container`	字符串、元素、假	`false`	将工具提示附加到特定元素。例：。此选项特别有用，因为它允许您将工具提示放置在文档流中靠近触发元素的位置 – 这将防止工具提示在调整窗口大小期间从触发元素上浮动。`container: 'body'`
`customClass`	字符串，函数	`''`	在工具提示显示时将其添加到工具提示中。请注意，除了模板中指定的任何类之外，还将添加这些类。要添加多个类，请用空格分隔它们：。您还可以传递一个函数，该函数应返回包含其他类名的单个字符串。`'class-1 class-2'`
`delay`	number，对象	`0`	显示和隐藏工具提示的延迟（毫秒）——不适用于手动触发器类型。如果提供了数字，则延迟将应用于隐藏/显示。对象结构为：。`delay: { "show": 500, "hide": 100 }`
`fallbackPlacements`	数组	`['top', 'right', 'bottom', 'left']`	通过在数组中提供展示位置列表（按优先顺序）来定义回退展示位置。有关更多信息，请参阅 Popper 的行为文档。
`html`	布尔	`false`	允许在工具提示中使用 HTML。如果为 true，则工具提示中的 HTML 标记将在工具提示中呈现。如果为 false，则属性将用于将内容插入 DOM。在处理用户生成的输入时，首选文本以防止 XSS 攻击。`titleinnerText`
`offset`	数组，字符串，函数	`[0, 6]`	工具提示相对于其目标的偏移量。您可以在数据属性中传递一个字符串，其中包含逗号分隔值，例如：。当使用函数确定偏移量时，调用该函数时，将使用包含 popper 放置、引用和 popper 矩形的对象作为其第一个参数。触发元素 DOM 节点作为第二个参数传递。该函数必须返回一个包含两个数字的数组：skidding、distance。有关更多信息，请参阅 Popper 的偏移文档。`data-bs-offset="10,20"`
`placement`	字符串，函数	`'top'`	如何定位工具提示：自动、顶部、底部、左、右。指定后，它将动态地重新定向工具提示。当使用函数确定放置时，调用该函数时，工具提示 DOM 节点作为第一个参数，触发元素 DOM 节点作为第二个参数。上下文设置为工具提示实例。`autothis`
`popperConfig`	空，对象，函数	`null`	要更改 Bootstrap 的默认 Popper 配置，请参阅 Popper 的配置。当使用函数创建 Popper 配置时，它会使用包含 Bootstrap 默认 Popper 配置的对象调用。它可以帮助您使用默认值并将其与您自己的配置合并。该函数必须返回 Popper 的配置对象。
`sanitize`	布尔	`true`	启用内容清理。如果为 true，则将对、和选项进行清理。`templatecontenttitle` 禁用内容清理时要小心。有关详细信息，请参阅 OWASP 的跨站点脚本预防备忘单。仅由禁用内容清理引起的漏洞不被视为 Bootstrap 安全模型的范围内。
`sanitizeFn`	null，函数	`null`	提供替代内容清理功能。如果您更喜欢使用专用库来执行清理，这会很有用。
`selector`	字符串，假	`false`	如果提供了选择器，则工具提示对象将委托给指定的目标。在实践中，这也用于将工具提示应用于动态添加的 DOM 元素（支持）。请参阅此问题和信息丰富的示例。注意：属性不得用作选择器。`jQuery.ontitle`
`template`	字符串	`'<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'`	创建工具提示时要使用的基本 HTML。工具提示将被注入到 . 将成为工具提示的箭头。最外层的包装器元素应该具有类和 .`title.tooltip-inner.tooltip-arrow.tooltiprole="tooltip"`
`title`	字符串，元素，函数	`''`	工具提示标题。如果给定了一个函数，则调用该函数时，其引用设置为弹出框所附加的元素。`this`
`trigger`	字符串	`'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 元素上存储的数据）。使用委派的工具提示（使用`选择器`选项创建）不能在后代触发器元素上单独销毁。
`enable`	使元素的工具提示能够显示。默认情况下，工具提示处于启用状态。
`getInstance`	静态方法，允许您获取与 DOM 元素关联的工具提示实例。
`getOrCreateInstance`	静态方法，允许您获取与 DOM 元素关联的工具提示实例，或创建一个新实例，以防它未初始化。
`hide`	隐藏元素的工具提示。在工具提示实际隐藏之前（即事件发生之前）返回给调用方。这被视为工具提示的“手动”触发。`hidden.bs.tooltip`
`setContent`	提供一种在初始化后更改工具提示内容的方法。
`show`	显示元素的工具提示。在工具提示实际显示之前（即在事件发生之前）返回给调用方。这被视为工具提示的“手动”触发。永远不会显示长度为零的标题的工具提示。`shown.bs.tooltip`
`toggle`	切换元素的工具提示。在工具提示实际显示或隐藏之前（即在 or 事件发生之前）返回给调用方。这被视为工具提示的“手动”触发。`shown.bs.tooltiphidden.bs.tooltip`
`toggleEnabled`	切换元素的工具提示显示或隐藏功能。
`update`	更新元素工具提示的位置。

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

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

该方法接受一个参数，其中每个属性键都是工具提示模板中的有效选择器，并且每个相关的属性值可以是 | | |setContentobjectstringstringelementfunctionnull

事件

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

Bootstrap V5.3 中文手册

入门指南 Getting started

定制化 Customize

布局方式 Layout

内容样式 Content

表单控件 Forms

组件集合 Components

辅助工具 Helpers

工具类库 Utilities

功能扩展 Extend

关于Bootstrap

Tooltips 工具提示

概述

例子

启用工具提示

链接上的工具提示

自定义工具提示

方向

CSS系统

变量

Sass 变量

用法

标记

禁用元素

选项

单个工具提示的数据属性

将函数与`popperConfig`

方法

事件

Tooltips 工具提示

概述

例子

启用工具提示

链接上的工具提示

自定义工具提示

方向

CSS系统

变量

Sass 变量

用法

标记

禁用元素

选项

单个工具提示的数据属性

将函数与popperConfig

方法

事件

将函数与`popperConfig`