bootstrap_ref_js_popover

Bootstrap 5 JS 弹出框

JS 弹出框 (popover.js)

弹出框（Popover）插件类似于工具提示（tooltips），但可以包含更多内容，包括标题和正文。当用户与元素交互（例如，点击）时会显示。

插件依赖：弹出框需要 Popper.js 进行定位。Bootstrap 的 bootstrap.bundle.min.js 包含了 Popper，所以如果你使用它，就已经涵盖了依赖。如果单独引入脚本，请确保在加载 popover.js 之前加载 Popper。

关于弹出框的总体介绍，请参阅 Bootstrap 官方弹出框文档。

通过 data-bs-* 属性

data-bs-toggle="popover" 用于激活弹出框。

title 属性（或 data-bs-title）指定弹出框的标题文本。

data-bs-content 属性指定应显示在弹出框正文中的文本或 HTML。

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

<!-- 重要：弹出框必须通过 JavaScript 初始化后才能工作。 -->
<script>
  var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
  var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
    return new bootstrap.Popover(popoverTriggerEl)
  })
</script>

<!-- 实际应用：可用于显示扩展信息、用户个人资料摘要或上下文帮助。 -->

通过 JavaScript

弹出框必须通过 JavaScript 初始化。选择元素并调用 Popover 构造函数。

// 初始化页面上的所有弹出框
var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
  return new bootstrap.Popover(popoverTriggerEl)
});

// 初始化一个带有自定义选项的单个弹出框
var exampleEl = document.getElementById('myPopoverElement');
var popover = new bootstrap.Popover(exampleEl, {
  content: 'This is the popover content via JavaScript.',
  placement: 'top'
});

// 常见障碍：忘记初始化弹出框。只使用 data 属性它们将无法工作。

弹出框选项

选项可以通过 data-bs-* 属性或 JavaScript 传递。对于 data 属性，将选项名称附加到 data-bs- 后面，例如 data-bs-placement="top"。

名称	类型	默认值	描述 (Bootstrap 5)	Data Attribute 示例 (如适用)
animation	boolean	true	对弹出框应用 CSS 淡入淡出过渡效果。
container	string | element | false	false	将弹出框附加到指定元素。示例：container: 'body' 或 data-bs-container="body"。这对于避免复杂组件中的渲染问题很有用。
content	string | element | function	''	默认内容值，如果不存在 data-bs-content 属性则使用此值。也可以是一个返回内容的函数。
delay	number | object	0	延迟显示和隐藏弹出框（毫秒）。对象结构：delay: { "show": 500, "hide": 100 }。
html	boolean	false	允许在弹出框中使用 HTML。如果为 false，将使用 jQuery 的 text() 方法（Bootstrap 5 在 DOMParser 不可用/不安全时内部使用 textContent）。如果你信任内容，请设置为 true。data-bs-html="true"。
placement	string | function	'right'	如何定位弹出框：auto、top、bottom、left、right。可以是一个函数。data-bs-placement="left"。
selector	string | false	false	如果提供选择器，弹出框对象将被委托给指定目标。适用于动态添加的内容。
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 中。
title	string | element | function	''	默认标题值，如果不存在 title 属性则使用此值。可以是一个函数。
trigger	string	'click'	弹出框如何触发：click、hover、focus、manual。可以传递多个触发器，用空格分隔。data-bs-trigger="hover focus"。
offset	array | string | function	[0, 8]	(Popper 选项) 弹出框相对于其目标的偏移量。例如，[10, 20] 或 '10,20' 或 data-bs-offset="10,20"。
fallbackPlacements	array	['top', 'right', 'bottom', 'left']	(Popper 选项) 定义回退定位顺序，如果原始定位无法计算则按此顺序尝试。
customClass	string | function	''	弹出框显示时添加的类。data-bs-custom-class="my-custom-popover"。
allowList	object	Default Allow List	包含允许的属性和标签的对象，用于在 html 为 true 时对 HTML 内容进行消毒。详情请参阅 Bootstrap 文档。

弹出框方法

下表列出了所有可用的弹出框方法。在 Popover 实例上调用它们（例如，myPopover.show()）。

方法	描述
show()	显示元素的弹出框。
hide()	隐藏元素的弹出框。
toggle()	切换元素的弹出框显示/隐藏状态。
dispose()	隐藏并销毁元素的弹出框。（移除 DOM 元素上存储的数据）
enable()	使元素的弹出框能够显示。
disable()	移除元素的弹出框显示能力。
toggleEnabled()	切换元素的弹出框显示或隐藏能力。
update()	更新元素的弹出框位置。
getInstance(element)	静态方法，允许你获取与 DOM 元素关联的弹出框实例。
getOrCreateInstance(element, [config])	静态方法，允许你获取与 DOM 元素关联的弹出框实例，如果尚未初始化则创建新的实例。

弹出框事件

下表列出了所有可用的弹出框事件。这些事件在触发弹出框的元素上触发。

事件	描述
show.bs.popover	当调用 show 实例方法时，此事件会立即触发。
shown.bs.popover	当弹出框对用户可见时（会等待 CSS 过渡完成），此事件会触发。
hide.bs.popover	当调用 hide 实例方法时，此事件会立即触发。
hidden.bs.popover	当弹出框完成隐藏时（会等待 CSS 过渡完成），此事件会触发。
inserted.bs.popover	在 show.bs.popover 事件之后触发，表示弹出框模板已添加到 DOM 中。

自定义弹出框样式

你可以使用 CSS 自定义弹出框的外观。Bootstrap 5 为许多组件使用了 CSS 变量，这使得自定义更加容易。你可以针对 .popover、.popover-header、.popover-body 和 .popover-arrow 进行样式设置。

/* 示例：自定义弹出框样式 */

/* 使用直接 CSS 覆盖 */
.popover-header {
  background-color: #0dcaf0; /* Bootstrap 的信息颜色 */
  color: white;
  font-size: 1.25rem;
  text-align: center;
}

.popover-body {
  background-color: #e9ecef; /* 浅灰色 */
  color: #212529;
  padding: 1rem;
}

/* 示例：使用 Bootstrap CSS 变量进行自定义 */
/* 将此代码放在你的自定义 CSS 文件中，该文件需在 Bootstrap 之后加载 */
:root {
  --bs-popover-header-bg: #6f42c1; /* 自定义紫色 */
  --bs-popover-header-color: #fff;
  --bs-popover-body-color: #333;
  --bs-popover-border-color: rgba(0,0,0,.1);
  --bs-popover-arrow-outer-color: rgba(0,0,0,.1);
}

/* 你也可以通过 'customClass' 选项创建一个自定义类 */
.my-custom-popover .popover-header {
  background-color: green;
}

/* 资源：查看 Bootstrap 的 _popover.scss 文件以获取所有可用的 CSS 变量：
   https://github.com/twbs/bootstrap/blob/main/scss/_popover.scss */