弹出提示框（Popovers）

Bootstrap弹出提示框的文件与示例，风格类似iOS，可加在网页上的任何元素上。

On this page

概述

使用popover插件时需要注意的事项：

Popovers依靠第三方库Popper进行定位。您必须在bootstrap.js之前包含popper.min.js，或者使用bootstrap.bundle.min.js/bootstrap.bundle.js，其中包含popper，这样popover才能工作！
Popovers需要工具提示插件作为依赖项。
由于性能原因，popover是选择加入的，所以您必须自己初始化它们。
长度为零的标题和内容值永远不会显示popover。
指定container:'body'以避免在更复杂的组件（如输入组、按钮组等）中呈现问题。
触发隐藏元素上的弹出窗口将不起作用。
必须在包装器元素上触发.disabled或disabled元素的弹出窗口。
当从环绕多行的锚点触发时，弹出窗口将在锚点的总宽度之间居中。在a上使用.text-nowrap可避免此行为。
必须先隐藏popover，然后才能从DOM中删除相应的元素。
由阴影DOM中的元素，可以触发弹出窗口。

默认情况下，此组件使用内置的内容清理器，该清理器将删除任何不明确允许的HTML元素。有关更多详细信息，请参阅JavaScript文档中的“消毒液”部分

此组件的动画效果取决于“首选简化运动媒体”查询。请参阅我们的可访问性文档的简化运动部分。

继续阅读一些例子，看看popover是如何工作的。

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

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

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

示例：使用容器选项

当父元素上的某些样式干扰popover时，您需要指定一个自定义容器，以便popover的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中使用引导时，方向是镜像的。

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

再一次单击时关闭

在用户下一次单击不同于toggle元素的元素时，使用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属性的元素不是交互式的，这意味着用户不能悬停或单击它们来触发popover（或工具提示）。作为一种解决方法，您需要从包装器div或span触发popover，最好使用tabindex=“0”使键盘可聚焦。

对于禁用的popover触发器，您也可能更喜欢data-bs-trigger="hover focus"，这样popover会显示为对用户的即时视觉反馈，因为用户可能不希望单击禁用的元素。

<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

Variables

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

让弹出提示框对键盘与辅助技术的用户有效

要让键盘用户启用您的弹出提示框，您应该只将它们添加到传统可被键盘focus和互动的HTML元素（像是连接或是表单元件）。虽然任意的HTML元素（像是span）都可以透过加上tabindex=“0”属性来focus，但这会让键盘用户对这些无法互动的元素感到讨厌和疑惑，并且大多的辅助技术都不会在这种情况下读取弹出提示框的内容。另外，请不要仅使用hover来触发您的弹出提示框，因为键盘用户无法触发它们。

虽然您可插入丰富、有结构的html选项到弹出提示框中，但我们强烈建议您避免增加过多的内容。它们目前的运作方式是一旦显示，它的内容将会触发绑定到aria-describedby属性。基于此结果，弹出提示框的所有内容将会被辅助技术如流水般的全部读出。

此外，尽管弹出提示框中可以包含互动元件（例如：表单元素或是连接）（透过增加这些元素到allowList所允许的属性和标签），但请注意，当前弹出提示框不会管理键盘focus顺序。当键盘用户打开弹出提示框，focus仍会停留在触发的元素上，且因为弹出视窗并不会立即跟着document结构被触发，因此无法保证键盘用户能使用向前/点击TAB来移动到弹出提示框中。简而言之，随意将互动元件加入到弹出提示框可能会使这些元件无法被键盘用户或辅助技术者读取或使用，或者使foucs顺序不合逻辑。在这样的情况下，请考虑优先使用modal dialog。

选项

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

基于安全性的原因，data属性不提供sanitize，sanitizeFn和allowList选项。

Name	Type	Default	Description
`animation`	boolean	`true`	对popover应用CSS淡入淡出过渡
`container`	string \| element \| false	`false`	将popover附加到特定元素。示例：container:'body'。此选项特别有用，因为它允许您将popover放在触发元素附近的文档流中，这将防止popover在调整窗口大小时从触发元素中浮动。
`content`	string \| element \| function	`''`	如果数据内容属性不存在，则为默认内容值。如果给定一个函数，它将被调用，其this引用设置为popover所附加到的元素。
`delay`	number \| object	`0`	延迟显示和隐藏popover（ms）-不适用于手动触发器类型如果提供了数字，则对隐藏/显示都应用延迟对象结构是：`delay: { "show": 500, "hide": 100 }`
`html`	boolean	`false`	在popover中插入HTML。如果为false，innerText属性将用于将内容插入DOM。如果您担心XSS攻击，请使用文本。
`placement`	string \| function	`'right'`	如何定位popover-自动\|顶部\|底部\|左侧\|右侧？当指定auto时，它将动态地重新定向popover。当一个函数用于确定位置时，调用它时，popover DOM节点是它的第一个参数，触发元素DOM节点是它的第二个参数。此上下文设置为popover实例。
`selector`	string \| false	`false`	如果提供了选择器，popover对象将被委托给指定的目标。实际上，这是用来使动态HTML内容添加popover的。请看这个和一个信息丰富的例子。
`template`	string	`'<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'`	创建popover时要使用的基本HTML。 opover的标题将被注入到.popover头中。弹出提示框的content将被注入到.popover-body中。 `.popover-arrow` 将成为弹出提示框的箭头。最外层的元素必须有.popover这个class。
`title`	string \| element \| function	`''`	如果标题属性不存在，则为默认标题值。如果给定一个函数，它将被调用，其this引用设置为popover所附加到的元素。
`trigger`	string	`'click'`	如何触发弹出窗口-单击\|悬停\|聚焦\|手动。您可以传递多个触发器；用空格隔开。手动不能与任何其他触发器组合。
`fallbackPlacements`	array	`['top', 'right', 'bottom', 'left']`	通过提供数组中的放置列表（按优先顺序）定义回退位置。有关更多信息，请参阅波普尔的行为文档
`boundary`	string \| element	`'clippingParents'`	opover的溢出约束边界。默认情况下，它是'clippingParents'，可以接受HTMLElement引用（仅限于JavaScript）。有关更多信息，请参阅波普尔的文件。
`customClass`	string \| function	`''`	在弹出窗口显示时向其添加类。请注意，这些类将添加到模板中指定的任何类之外。要添加多个类，请用空格分隔它们：“class-1 class-2”。还可以传递一个函数，该函数应返回一个包含其他类名的字符串。
`sanitize`	boolean	`true`	启用或禁用消毒。如果激活“模板”，“内容”和“标题”选项将被清除。请参阅我们的JavaScript文档中的消毒剂部分。
`allowList`	object	Default value	包含允许的属性和标记的对象
`sanitizeFn`	null \| function	`null`	在这里，您可以提供您自己的消毒功能。如果您喜欢使用专用的库来执行清理，这将非常有用。
`offset`	array \| string \| function	`[0, 8]`	popover相对于其目标的偏移量。您可以用逗号分隔的值在数据属性中传递字符串，例如：data bs offset=“10,20” 当一个函数用于确定偏移量时，调用它的第一个参数是包含popper放置、引用和popper rects的对象。触发元素DOM node作为第二个参数传递。函数必须返回一个包含两个数字的数组：[滑动，距离]。 `[滑动, 距离]`. 有关更多信息，请参阅波普尔的抵销单。 offset docs.
`popperConfig`	null \| object \| function	`null`	要更改引导的默认Popper配置，请参阅Popper的配置。 Popper's configuration. 当一个函数被用来创建Popper配置时，它被一个包含引导的默认Popper配置的对象调用。它可以帮助您使用默认配置并将其与您自己的配置合并。函数必须返回Popper的配置对象。

单个popover的数据属性

也可以通过使用数据属性来指定各个popover的选项，如上所述。

将函数与popperConfig一起使用

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

方法

Asynchronous methods and transitions

All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started but before it ends. In addition, a method call on a transitioning component will be ignored.

See our JavaScript documentation for more information.

显示

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

myPopover.show()

隐藏

隐藏元素的弹出提示框。在弹出提示框实际被隐藏之前返回给调用者（也就是在hidden.bs.popover事件发生之前。）弹出提示框会被认为是“manual”触发。

myPopover.hide()

切换

切换元素的弹出提示框。在弹出提示框实际被显示或隐藏之前返回给调用者（也就是在shown.bs.popover或hidden.bs.popover事件发生之前。）弹出提示框会被认为是“manual”触发。

myPopover.toggle()

销毁

隐藏和销毁一个元素的弹出提示框（将移除在DOM元素上储存的数据。）被委派的弹出提示框（使用the selector option创建）不能在后代触发元素上单独销毁。

myPopover.dispose()

可用

使元素的弹出提示框能够显示。弹出提示框预设启用显示。

myPopover.enable()

禁用

取消显示元素的popover的功能。只有重新启用时才能显示popover。

myPopover.disable()

切换可用

切换显示或隐藏弹出提示框功能。

myPopover.toggleEnabled()

更新

更新弹出提示框的位置。

myPopover.update()

获取实例

允许您取得DOM元素上弹出提示框实体的静态方法。

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

事件

Event type	Description
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...
})