工具提示

使用工具提示插件时要知道的事情:

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

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

杨素 知隋主最惧内,最听妇人言的,每每乘内宴时,称扬晋王贤孝,挑拨 独孤皇后。妇人心肠褊窄浅露,便把 晋王 好,太子歹,一齐搬将出来。杨素又加上些冷言热语。皇后知他是外廷最信任的,便托他赞成废立,暗地将金宝送来嘱他。杨素初时,还望皇后助他,这时皇后反要他相帮,知事必成。于是不时在 隋主 前,搬斗是非;又日令宦官官妾,乘隙进谗,冷一句,热一句,说他不好的去处。

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

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="顶部的工具提示">
        顶部的工具提示
      </button>
      <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="右侧的工具提示">
        右侧的工具提示
      </button>
      <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="底部的工具提示">
        底部的工具提示
      </button>
      <button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" title="左侧的工具提示">
        左侧的工具提示
      </button>

并添加了自定义 HTML:

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
        Tooltip with HTML
      </button>

使用 SVG:

用法

工具提示插件按需生成内容和标记,默认情况下将工具提示放置在其触发元素之后。

通过 JavaScript 触发工具提示:

var exampleEl = document.getElementById('example')
      var tooltip = new bootstrap.Tooltip(exampleEl, options)
溢出自动和滚动

当父容器溢出时,工具提示位置尝试自动更改:overflow: auto 或者 overflow: scroll 像我们的 .table-responsive 一样滚动,但仍保持原始位置的定位。 要解决此问题,请将边界选项(用于使用 popperConfig 选项的翻转修饰符)设置为任何 HTMLElement 以覆盖默认值 'clippingParents',例如 document.body:

var exampleEl = document.getElementById('example')
      var tooltip = new bootstrap.Tooltip(exampleEl, {
        boundary: document.body // or document.querySelector('#boundary')
      })
标记

工具提示所需的标记只是您希望拥有工具提示的 HTML 元素上的数据属性和标题。 生成的工具提示标记相当简单,尽管它确实需要一个位置(默认情况下,由插件设置为顶部)。

使工具提示适用于键盘和辅助技术用户

您应该只将工具提示添加到传统上可通过键盘聚焦和交互的 HTML 元素(例如链接或表单控件)。 尽管可以通过添加 tabindex="0" 属性使任意 HTML 元素(例如 <span>s)成为焦点,但这会在非交互式元素上为键盘用户添加可能令人讨厌和令人困惑的制表位,目前大多数辅助技术都会这样做 在这种情况下不宣布工具提示。 此外,不要仅仅依靠悬停作为工具提示的触发器,因为这会使键盘用户无法触发工具提示。

<!-- HTML to write -->
      <a href="#" data-bs-toggle="tooltip" 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" 使键盘可聚焦。

选项

选项可以通过数据属性或 JavaScript 传递。 对于数据属性,将选项名称附加到 data-bs-,如 data-bs-animation=""。 通过数据属性传递选项时,请确保将选项名称的大小写类型从驼峰式大小写更改为短横线隔开式。 例如,不要使用 data-bs-customClass="beautifier",而是使用 data-bs-custom-class="beautifier"。

请注意,出于安全原因,无法使用数据属性提供 sanitize、sanitizeFn 和 allowList 选项。
名称 类型 默认值 说明
animation boolean true 对工具提示应用 CSS 淡入淡出过渡
container string | element | false false

将工具提示附加到特定元素。 例子: container: 'body'。此选项特别有用,因为它允许您将工具提示定位在触发元素附近的文档流中 - 这将防止工具提示在窗口调整大小期间从触发元素浮动。

delay number | object 0

延迟显示和隐藏工具提示 (ms) - 不适用于手动触发类型

如果提供了一个数字,延迟将应用于隐藏/显示

对象结构为:delay: { "show": 500, "hide": 100 }

html boolean false

允许在工具提示中使用HTML。

如果为 true,则在工具提示的 title 将在工具提示中呈现。如果为 false,将使用 innerText 属性将内容插入DOM。

如果担心XSS攻击,请使用文本。

placement string | function 'top'

如何定位工具提示 - 自动 | 顶部 | 底部 | 左侧 | 右侧。
当 auto 被指定时,它会动态地重新定位工具提示。

当一个函数用于确定位置时,它会以工具提示 DOM 节点作为其第一个参数,触发元素 DOM 节点作为其第二个参数来调用。 this 上下文设置为工具提示实例。

selector string | false false 如果提供了选择器,则工具提示对象将被委托给指定的目标。 实际上,这也用于将工具提示应用于动态添加的 DOM 元素(jQuery.on 支持)。请参阅 这个 和 一个信息丰富的例子。
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' 表示工具提示将通过 .show()、.hide() 和 .toggle( ) 方法; 此值不能与任何其他触发器组合。

'hover' 本身将导致无法通过键盘触发的工具提示,并且只有在存在为键盘用户传达相同信息的替代方法时才应使用。

fallbackPlacements array ['top', 'right', 'bottom', 'left'] 通过提供数组中的展示位置列表(按优先顺序)来定义后备展示位置。 有关更多信息,请参阅 行为文档
boundary string | element 'clippingParents' 工具提示的溢出约束边界(仅适用于 Popper 的 preventOverflow 修饰符)。默认情况下它是 'clippingParents' 并且可以接受 HTMLElement 引用(仅通过 JavaScript)。欲了解更多信息,请参阅 Popper 的 检测溢出文档.
customClass string | function ''

显示时将类添加到工具提示。 请注意,除了模板中指定的任何类之外,还将添加这些类。 要添加多个类,请用空格分隔它们:'class-1 class-2'。

您还可以传递一个函数,该函数应返回包含其他类名的单个字符串。

sanitize boolean true 启用或禁用清理。 如果激活 'template' 和 'title' 选项将被清理。 请参阅我们的 JavaScript 文档中的 sanitizer 部分。
allowList object Default value 包含允许的属性和标签的对象
sanitizeFn null | function null 在这里,您可以提供自己的 sanitize 方法。 如果您更喜欢使用专用库来执行清理,这会很有用。
offset array | string | function [0, 0]

工具提示相对于其目标的偏移量。 您可以使用逗号分隔值在数据属性中传递字符串,例如:data-bs-offset="10,20"。

当一个函数用于确定偏移量时,调用它时会使用一个包含 popper 位置、引用和 popper rects 作为其第一个参数的对象。 触发元素 DOM 节点作为第二个参数传递。 该函数必须返回一个包含两个数字的数组:[skidding, distance]。

有关更多信息,请参阅 Popper 的 offset 文档。

popperConfig null | object | function null

更改 Bootstrap 的默认 Popper 配置, 参考 Popper 的配置。

当一个函数用于创建 Popper 配置时,它会被一个包含 Bootstrap 的默认 Popper 配置的对象调用。 它可以帮助您使用默认设置并将其与您自己的配置合并。 该函数必须为 Popper 返回一个配置对象。

单个工具提示的数据属性

如上所述,可以通过使用数据属性来指定单个工具提示的选项。

使用带有 popperConfig 的函数

var tooltip = new bootstrap.Tooltip(element, {
        popperConfig: function (defaultBsPopperConfig) {
          // var newPopperConfig = {...}
          // use defaultBsPopperConfig if needed...
          // return newPopperConfig
        }
      })
方法
异步方法和转换

所有 API 方法都是异步的并开始一个转换。 他们在转换开始但在结束之前立即返回给调用者。 此外,过渡组件上的方法调用将被忽略。

show

显示元素的工具提示。在工具提示实际显示之前(即在 shown.bs.tooltip 事件发生之前)返回给调用者。这被认为是工具提示的“手动”触发。从不显示具有零长度标题的工具提示。

tooltip.show()
hide

隐藏元素的工具提示。 在工具提示实际被隐藏之前(即在 hidden.bs.tooltip 事件发生之前)返回给调用者。 这被认为是工具提示的“手动”触发。

tooltip.hide()
toggle

切换元素的工具提示。 在工具提示实际显示或隐藏之前返回给调用者(即在 shown.bs.tooltip 或 hidden.bs.tooltip 事件发生之前)。 这被认为是工具提示的“手动”触发。

tooltip.toggle()
dispose

隐藏和销毁元素的工具提示(删除 DOM 元素上存储的数据)。 使用委托(使用选择器选项创建)的工具提示不能在后代触发器元素上单独销毁。

tooltip.dispose()
enable

使元素的工具提示能够显示。 默认情况下启用工具提示。

tooltip.enable()
disable

移除显示元素工具提示的能力。 工具提示只有在重新启用后才能显示。

tooltip.disable()
setContent

提供一种在初始化后更改工具提示内容的方法。

tooltip.setContent({ '.tooltip-inner': 'another title' })
setContent 方法接受一个对象参数,其中每个属性键是弹出框模板中的有效字符串选择器,每个相关的属性值可以是 string | element | function | null。
toggleEnabled

切换显示或隐藏元素工具提示的能力。

tooltip.toggleEnabled()
update

更新元素工具提示的位置。

tooltip.update()
getInstance

允许您获取与 DOM 元素关联的工具提示实例的静态方法。

var exampleTriggerEl = document.getElementById('example')
      var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
getOrCreateInstance

静态方法,允许您获取与 DOM 元素关联的工具提示实例,或者在未初始化的情况下创建一个新实例。

var exampleTriggerEl = document.getElementById('example')
      var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
事件
事件类型 描述
show.bs.tooltip 此事件在调用 show 实例方法时立即触发。
shown.bs.tooltip 当工具提示对用户可见时触发此事件(将等待 CSS 转换完成)。
hide.bs.tooltip 当调用 hide 实例方法时,会立即触发此事件。
hidden.bs.tooltip 当工具提示完成对用户隐藏时触发此事件(将等待 CSS 转换完成)。
inserted.bs.tooltip 当工具提示模板已添加到 DOM 时,此事件在 show.bs.tooltip 事件之后触发。
var myTooltipEl = document.getElementById('myTooltip')
      var tooltip = new bootstrap.Tooltip(myTooltipEl)

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

      tooltip.hide()