弹出框

用于将Bootstrap弹出窗口（如iOS中发现的）添加到网站上任何元素的文档和示例。

在本页面

概述

使用弹出框（popover）插件时需要注意的事项

弹出框依靠第三方库Popper进行定位。你必须在 bootstrap.js之前包含popper.min.js，或使用 bootstrap.bundle.min.js / bootstrap.bundle.js包含Popper才能使弹出框起作用！
弹出框需要工具提示插件作为依赖项。
由于性能原因，弹出框是可选的，因此 您必须自己对其进行初始化。
零长度 title 和 content 值永远不会显示框。
指定 container: 'body' 以避免在更复杂的组件（例如我们的输入组，按钮组等）中呈现问题。
在隐藏元素上触发弹出框将不起作用。
.disabled 或 disabled 元素的弹出框必须在包装器元素上触发。
从跨越多行的锚点触发时，弹出框将在锚点的整体宽度之间居中。在.text-nowrap 上使用 <a>可以避免这种情况。
弹出框必须先隐藏，然后才能从DOM中删除其相应元素。
由于阴影DOM中的元素，可以触发弹出框。

此组件的动画效果取决于 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="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  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="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  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="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  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="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  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> 触发弹出框，并重写禁用元素上的 pointer-events。

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

<span class="d-inline-block" data-bs-toggle="popover" data-bs-content="Disabled popover">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

用法

通过JavaScript启用弹出框：

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

使弹出框为键盘和辅助技术用户工作

要允许键盘用户激活弹出框，您应该只将它们添加到传统上键盘可聚焦和交互的HTML元素（例如链接或表单控件）。尽管通过添加tabindex="0"属性可以使任意HTML元素（如<span>）成为焦点，但这将为键盘用户在非交互元素上添加潜在的恼人和混乱的制表位，并且大多数辅助技术目前不会在这种情况下公布弹出框的内容。另外，不要仅仅依靠hover作为弹出框的触发器，因为这将使键盘用户无法触发弹出框。

虽然您可以使用 html选项在弹出框中插入丰富的结构化HTML，但我们强烈建议您避免添加过多的内容。弹出框当前的工作方式是，一旦显示，它们的内容就被绑定到具有 aria-describedby属性的触发器元素。因此，弹出框的全部内容将作为一个长的、不间断的流向辅助技术用户公布。

此外，虽然也可以在弹出框中包含交互控件（例如表单元素或链接）（通过将这些元素添加到允许的属性和标记的allowList中），但请注意，弹出框当前不管理键盘焦点顺序。当键盘用户打开弹出框时，焦点仍在触发元素上，并且由于弹出框通常不会立即跟随文档结构中的触发器，因此不能保证向前移动/按 TAB键会将键盘用户移动到弹出框本身中。简而言之，简单地在弹出框中添加交互控件很可能会使键盘用户和辅助技术用户无法访问/无法使用这些控件，或者至少会导致整体焦点顺序不合逻辑。在这些情况下，请考虑改用模态对话框。

选项

选项可以通过数据属性或JavaScript传递。对于数据属性，将选项名称附加到 data-bs-，如 data-bs-animation=""中所示。

请注意，出于安全原因，不能使用数据属性提供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`	延迟显示和隐藏弹出框（ms）--不适用于手动触发器类型如果提供了数字，则对隐藏/显示都应用延迟对象结构是： `delay: { "show": 500, "hide": 100 }`
`html`	boolean	`false`	在弹出框中插入HTML。如果为false，`innerText` 属性将用于将内容插入DOM。如果您担心XSS攻击，请使用文本。
`placement`	string \| function	`'right'`	如何定位弹出框-自动\|顶部\|底部\|左侧\|右侧。当指定 `auto`时，它将动态地重新定向弹出框。当一个函数用于确定位置时，调用它时，弹出框 DOM节点是它的第一个参数，触发元素DOM节点是它的第二个参数。`this`上下文设置为弹出框实例。
`selector`	string \| false	`false`	如果提供了选择器，弹出框对象将被委托给指定的目标。实际上，这是用来使动态HTML内容添加弹出框的。请看这个和一个信息丰富的例子。
`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'`	如何触发弹出框-单击\|悬停\|聚焦\|手动。您可以传递多个触发器；用空格分隔它们。`manual`不能与任何其他触发器组合。
`offset`	number \| string	`0`	弹出框相对于其目标的偏移量。有关更多信息，请参阅 Popper的offset 文档。
`fallbackPlacement`	string \| array	`'flip'`	允许指定Popper在回退时使用的位置。有关更多信息，请参阅 Popper 行为文档。
`boundary`	string \| element	`'scrollParent'`	弹出框的溢出约束边界。接受 `'viewport'`, `'window'`, `'scrollParent'`或HTMLElement引用（仅限JavaScript）的值。有关更多信息，请参阅Popper的 preventOverflow 文档。
`customClass`	string \| function	`''`	在弹出框显示时向其添加类。请注意，这些类将添加到模板中指定的任何类之外。要添加多个类，请用空格分隔它们： `'class-1 class-2'`。还可以传递一个函数，该函数应返回一个包含其他类名的字符串。
`sanitize`	boolean	`true`	启用或禁用清除。如果激活 `'template'`, `'content'` 和 `'title'` 选项将被清除。
`allowList`	object	Default value	包含允许的属性和标记的对象。
`sanitizeFn`	null \| function	`null`	在这里您可以提供自己的清除函数。如果您喜欢使用专用的库来执行清除，这将非常有用。
`popperConfig`	null \| object	`null`	要更改Bootstrap的默认Popper配置，请参阅Popper的配置。

单个弹出框的数据属性

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

方法

异步方法和转换

所有API方法都是异步的，并开始转换。转换一开始就返回到调用方，但在转换 结束之前返回。此外，对转换组件的方法调用将被忽略。

有关更多信息，请参阅我们的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

事件

事件类型	描述
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...
})

弹出框

概述