Skip to main content Skip to docs navigation

弹出框(Popover)

将 Bootstrap 弹出框（如 iOS 中的弹出框）添加到您网站上的任何元素的文档和示例。

On this page

概述

使用 popover 插件时要知道的事情：

  • Popover 依赖第三方库 Popper.js 进行定位。 您必须引入 popper.min.js 或使用 bootstrap.bundle.min.js / bootstrap.bundle.js 其中包含了 Popper.js
  • 弹出框需要 工具提示插件 作为依赖项。
  • 如果您从源代码构建我们的 JavaScript，它需要 util.js。
  • 出于性能原因，弹出框是可选的，因此您必须自己初始化它们。
  • 零长度的 title 和 content 值永远不会显示弹出框。
  • 指定 container: 'body' 以避免在更复杂的组件（如我们的输入组、按钮组等）中出现渲染问题。
  • 在隐藏元素上触发弹出框将不起作用。
  • .disabled 或 disabled 元素的弹出框必须在包装器元素上触发。
  • 当从跨越多行的链接触发时，弹出框将在链接的整体宽度之间居中。 在你的 <a> 上使用 white-space: nowrap; 来避免这种行为。
  • 在从 DOM 中删除其相应元素之前，必须隐藏弹出框。
默认情况下，该组件使用内置的内容清理器，它会去除任何未明确允许的 HTML 元素。 有关详细信息，请参阅我们的 JavaScript 文档中的 sanitizer 部分。
该组件的动画效果依赖于 prefers-reduced-motion 媒体查询。 请参阅无障碍文档的减弱动画效果部分。

继续阅读以了解弹出框如何与一些示例一起使用。

示例：在任何地方启用弹出框

初始化页面上所有弹出框的一种方法是通过它们的 data-bs-toggle 属性选择它们：

var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
  return new bootstrap.Popover(popoverTriggerEl)
})

示例：使用 container 选项

当父元素上有一些样式会干扰弹出框时，您需要指定一个自定义 container 以便弹出框 HTML 出现在该元素中。

var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
  container: 'body'
})

示例

<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>

四个方向

有四个选项可用：上对齐、右对齐、下对齐和左对齐。 在 RTL 中使用 Bootstrap 时会是镜像方向。

<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
  Popover on top
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Right popover">
  Popover on right
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Bottom popover">
  Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Left popover">
  Popover on left
</button>

下次点击时关闭

使用 focus 触发器可以在用户下次单击与切换元素不同的元素时关闭弹出框。

下次单击时关闭所需的特定标记

为了正确的跨浏览器和跨平台行为，您必须使用 <a> 标签，而不是 <button> 标签， 并且您还必须包含 tabindex 属性。

Dismissible popover 
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
  trigger: 'focus'
})

禁用元素

具有 disabled 属性的元素不是交互式的，这意味着用户无法悬停或单击它们来触发弹出框（或工具提示）。 作为一种解决方法，您需要从包窠元素 <div> 或 <span> 触发弹出框，理想情况下使用 tabindex="0" 使键盘可聚焦 。

对于禁用的弹出框触发器，您可能还更喜欢 data-bs-trigger="hover focus" 以便弹出框以视觉上即时反馈的形式呈现给您的用户，因为他们可能不希望单击 禁用的元素。

<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Disabled popover">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

Sass

变量

$popover-font-size:                 $font-size-sm;
$popover-bg:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              rgba($black, .2);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;

$popover-header-bg:                 shade-color($popover-bg, 6%);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                $body-color;
$popover-body-padding-y:            $spacer;
$popover-body-padding-x:            $spacer;

$popover-arrow-width:               1rem;
$popover-arrow-height:              .5rem;
$popover-arrow-color:               $popover-bg;

$popover-arrow-outer-color:         fade-in($popover-border-color, .05);

用法

通过 JavaScript 启用弹出框：

var exampleEl = document.getElementById('example')
  var popover = new bootstrap.Popover(exampleEl, options)

选项

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

请注意，出于安全原因，不能使用数据属性提供 sanitize、sanitizeFn 和 allowList 选项。
名称 类型 默认值 描述
animation boolean true 对弹出框应用 CSS 淡入淡出过渡
container string | element | false false

将弹出框附加到特定元素。 示例：container:'body'。 此选项特别有用，因为它允许您将弹出框放置在文档流中靠近触发元素的位置 - 这将防止弹出框在窗口调整大小期间位置远离触发元素。
content string | element | function ''

如果 data-bs-content 属性不存在，则默认内容值。

如果给定了一个函数，它将被调用，并将其 this 引用设置为弹出框附加到的元素。
delay number | object 0

延迟显示和隐藏弹出框（毫秒） - 不适用于手动触发类型

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

对象结构为：delay: { "show": 500, "hide": 100 }
html boolean false 将 HTML 插入弹出框。 如果为 false，innerText 属性将用于将内容插入 DOM。 如果您担心 XSS 攻击，请使用文本。
placement string | function 'right'

如何定位弹出框 - auto | top | bottom | left | right。
当 auto 被指定时，它会动态地重新定位弹出框。

当一个函数用于确定位置时，它会以弹出框 DOM 节点作为其第一个参数，触发元素 DOM 节点作为其第二个参数来调用。 this 上下文设置为弹出框实例。
selector string | false false 如果提供了选择器，弹出框对象将被委托给指定的目标。 在实践中，这用于启用动态 HTML 内容以添加弹出框。 请参阅 this 和 一个信息丰富的例子。
template string '<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

创建弹出框时使用的基本 HTML。

弹出框的title会被注入到.popover-header中。

弹出框的content会被注入到.popover-body中。

.popover-arrow 将成为弹出框的箭头。

最外层的包装元素应该有 .popover 类。
title string | element | function ''

如果 title 属性不存在，则默认标题值。

如果给定了一个函数，它将被调用，并将其 this 引用设置为弹出框附加到的元素。
trigger string 'click' 弹出框是如何触发的 - click | hover | focus | manual。 您可以传递多个触发器； 用空格分隔它们。 manual 不能与任何其他触发器结合使用。
fallbackPlacements array ['top', 'right', 'bottom', 'left'] 通过提供数组中的展示位置列表（按优先顺序）来定义后备展示位置。 有关更多信息，请参阅 Popper 的 行为文档
boundary string | element 'clippingParents' popover 的溢出约束边界（仅适用于 Popper 的 preventOverflow 修饰符）。 默认情况下它是 'clippingParents' 并且可以接受 HTMLElement 引用（仅通过 JavaScript）。 有关详细信息，请参阅 Popper 的 detectOverflow 文档。
customClass string | function ''

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

您还可以传递一个函数，该函数应返回包含其他类名的单个字符串。
sanitize boolean true 启用或禁用清理。 如果激活 'template'，'content' 和 'title' 选项将被清理。 请参阅我们的 JavaScript 文档中的 sanitizer 部分。
allowList object Default value 包含允许的属性和标签的对象
sanitizeFn null | function null 在这里，您可以提供自己的清理功能。 如果您更喜欢使用专用库来执行清理，这会很有用。
offset array | string | function [0, 8]

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

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

有关详细信息，请参阅 Popper 的 偏移文档。
popperConfig null | object | function null

要更改 Bootstrap 的默认 Popper 配置，请参阅 Popper 的配置。

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

单个弹出框的数据属性

如上所述，可以通过使用数据属性来指定单个弹出框的选项。

使用函数的 popperConfig 

var popover = new bootstrap.Popover(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

方法

异步方法和过渡

所有 API 方法都是异步并启动transition。 它们会在过渡开始后但在过渡结束之前返回给调用者。 此外，过渡时调用组件上的方法，过渡将被忽略。

查看我们的 JavaScript 文档了解更多信息。

show

显示元素的弹出框。 在弹出框实际显示之前返回给调用者（即在 shown.bs.popover 事件发生之前）。 这被认为是弹出框的“手动”触发。 标题和内容都为零长度的弹出框永远不会显示。

myPopover.show()

hide

隐藏元素的弹出框。 在弹出框实际隐藏之前返回调用者（即在 hidden.bs.popover 事件发生之前）。 这被认为是弹出框的“手动”触发。

myPopover.hide()

toggle

切换元素的弹出框的显示和隐藏。 在弹出框实际显示或隐藏之前返回调用者（即在 shown.bs.popover 或 hidden.bs.popover 事件之前 发生）。 这被认为是弹出框的“手动”触发。

myPopover.toggle()

dispose

隐藏并销毁元素的弹出框（删除 DOM 元素上存储的数据）。 使用委托的弹出框（使用 selector 选项创建）不能在后代触发器元素上单独销毁。

myPopover.dispose()

enable

使元素的弹出框能够显示。 弹出框默认启用。

myPopover.enable()

disable

移除显示元素弹出框的能力。 只有重新启用弹出框才能显示。

myPopover.disable()

toggleEnabled

切换显示或隐藏元素弹出框的能力。

myPopover.toggleEnabled()

update

更新元素弹出框的位置。

myPopover.update()

getInstance

静态 方法，它允许您获取与 DOM 元素关联的弹出框实例

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

getOrCreateInstance

静态 方法允许您获取与 DOM 元素关联的弹出框实例，或者创建一个新的实例以防它未初始化

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

事件

事件类型 描述
show.bs.popover 此事件在调用 show 实例方法时立即触发。
shown.bs.popover 当弹出框对用户可见时触发此事件（将等待 CSS 过渡完成）。
hide.bs.popover 当调用 hide 实例方法时，会立即触发此事件。
hidden.bs.popover 当弹出窗口完成对用户隐藏时触发此事件（将等待 CSS 过渡完成）。
inserted.bs.popover 当弹出框模板添加到 DOM 时，此事件在 show.bs.popover 事件之后触发。 
var myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
  // do something...
})