将 Bootstrap 弹出框（如 iOS 中的弹出框）添加到网站上的任何元素的文档和示例。
概述
使用弹出插件时需要了解的事项：
- 爆米花依赖第三方库 Popper 进行定位。您必须在 之前包含 popper.min.js ，或者使用包含 Popper 的。
bootstrap.jsbootstrap.bundle.min.js - 弹出框需要弹出框插件作为依赖项。
- 弹出框是出于性能原因选择加入的，因此您必须自己初始化它们。
- 零长度和值永远不会显示弹出框。
titlecontent - 指定以避免在更复杂的组件（如我们的输入组、按钮组等）中出现渲染问题。
container: 'body' - 在隐藏元素上触发弹出框将不起作用。
- 或元素的弹出框必须在包装器元素上触发。
.disableddisabled - 当从跨多行换行的锚点触发时，弹出框将在锚点的整体宽度之间居中。在 s 上使用以避免此行为。
.text-nowrap<a> - 在从 DOM 中删除其相应元素之前，必须隐藏弹出框。
- 弹出框可以通过影子 DOM 中的元素触发。
默认情况下，此组件使用内置内容清理器，该清理器会去除任何未显式允许的 HTML 元素。有关更多详细信息，请参阅我们的 JavaScript 文档中的清理器部分。
此组件的动画效果取决于媒体查询。请参阅我们辅助功能文档的减少运动部分。prefers-reduced-motion
继续阅读以了解弹出框如何通过一些示例工作。
例子
启用弹出框
如上所述，您必须先初始化弹出框，然后才能使用它们。初始化页面上所有弹出框的一种方法是按其属性选择它们，如下所示：data-bs-toggle
const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]')
const popoverList = [...popoverTriggerList].map(popoverTriggerEl => new bootstrap.Popover(popoverTriggerEl))
现场演示
我们使用类似于上面代码段的 JavaScript 来呈现以下实时弹出框。标题通过 设置，正文内容通过 设置。data-bs-titledata-bs-content
请随意在您的 HTML 中使用 或。使用时，Popper 将自动替换为元素渲染时。titledata-bs-titletitledata-bs-title
<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" data-bs-title="Popover title" data-bs-content="And here’s some amazing content. It’s very engaging. Right?">Click to toggle popover</button>四个方向
有四个选项可用：顶部、右侧、底部和左侧。在 RTL 中使用 Bootstrap 时，方向会镜像。设置为更改方向。data-bs-placement
<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>习惯container
当您的父元素上有一些样式干扰弹出框时，您需要指定一个自定义，以便弹出框的 HTML 显示在该元素中。这在响应式表、输入组等中很常见。container
const popover = new bootstrap.Popover('.example-popover', {
container: 'body'
})
您想要设置显式自定义的另一种情况是模态对话框中的弹出框，以确保弹出框本身附加到模态。这对于包含交互式元素的弹出框尤为重要——模态对话框会捕获焦点，因此除非弹出框是模态的子元素，否则用户将无法聚焦或激活这些交互式元素。container
const popover = new bootstrap.Popover('.example-popover', {
container: '.modal-body'
})
自定义弹出框
在 v5.2.0 中添加您可以使用 CSS 变量自定义弹出框的外观。我们设置了一个自定义类 with 来限定我们的自定义外观，并使用它来覆盖一些本地 CSS 变量。data-bs-custom-class="custom-popover"
.custom-popover {
--bs-popover-max-width: 200px;
--bs-popover-border-color: var(--bd-violet-bg);
--bs-popover-header-bg: var(--bd-violet-bg);
--bs-popover-header-color: var(--bs-white);
--bs-popover-body-padding-x: 1rem;
--bs-popover-body-padding-y: .5rem;
}
<button type="button" class="btn btn-secondary"
data-bs-toggle="popover" data-bs-placement="right"
data-bs-custom-class="custom-popover"
data-bs-title="Custom popover"
data-bs-content="This popover is themed via CSS variables.">
Custom popover
</button>下次点击时关闭
使用触发器在用户下次单击切换元素以外的元素时关闭弹出框。focus
在下次单击时关闭需要特定的 HTML 才能实现正确的跨浏览器和跨平台行为。只能使用元素，不能使用 s，并且必须包含 tabindex。<a><button>
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" data-bs-title="Dismissible popover" data-bs-content="And here’s some amazing content. It’s very engaging. Right?">Dismissible popover</a>const popover = new bootstrap.Popover('.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>CSS系统
变量
在 v5.2.0 中添加作为 Bootstrap 不断发展的 CSS 变量方法的一部分，弹出框现在使用本地 CSS 变量来增强实时自定义。CSS 变量的值是通过 Sass 设置的，因此仍然支持 Sass 自定义。.popover
--#{$prefix}popover-zindex: #{$zindex-popover};
--#{$prefix}popover-max-width: #{$popover-max-width};
@include rfs($popover-font-size, --#{$prefix}popover-font-size);
--#{$prefix}popover-bg: #{$popover-bg};
--#{$prefix}popover-border-width: #{$popover-border-width};
--#{$prefix}popover-border-color: #{$popover-border-color};
--#{$prefix}popover-border-radius: #{$popover-border-radius};
--#{$prefix}popover-inner-border-radius: #{$popover-inner-border-radius};
--#{$prefix}popover-box-shadow: #{$popover-box-shadow};
--#{$prefix}popover-header-padding-x: #{$popover-header-padding-x};
--#{$prefix}popover-header-padding-y: #{$popover-header-padding-y};
@include rfs($popover-header-font-size, --#{$prefix}popover-header-font-size);
--#{$prefix}popover-header-color: #{$popover-header-color};
--#{$prefix}popover-header-bg: #{$popover-header-bg};
--#{$prefix}popover-body-padding-x: #{$popover-body-padding-x};
--#{$prefix}popover-body-padding-y: #{$popover-body-padding-y};
--#{$prefix}popover-body-color: #{$popover-body-color};
--#{$prefix}popover-arrow-width: #{$popover-arrow-width};
--#{$prefix}popover-arrow-height: #{$popover-arrow-height};
--#{$prefix}popover-arrow-border: var(--#{$prefix}popover-border-color);
Sass 变量
$popover-font-size: $font-size-sm;
$popover-bg: var(--#{$prefix}body-bg);
$popover-max-width: 276px;
$popover-border-width: var(--#{$prefix}border-width);
$popover-border-color: var(--#{$prefix}border-color-translucent);
$popover-border-radius: var(--#{$prefix}border-radius-lg);
$popover-inner-border-radius: calc(#{$popover-border-radius} - #{$popover-border-width}); // stylelint-disable-line function-disallowed-list
$popover-box-shadow: var(--#{$prefix}box-shadow);
$popover-header-font-size: $font-size-base;
$popover-header-bg: var(--#{$prefix}secondary-bg);
$popover-header-color: $headings-color;
$popover-header-padding-y: .5rem;
$popover-header-padding-x: $spacer;
$popover-body-color: var(--#{$prefix}body-color);
$popover-body-padding-y: $spacer;
$popover-body-padding-x: $spacer;
$popover-arrow-width: 1rem;
$popover-arrow-height: .5rem;
用法
通过 JavaScript 启用弹出框：
const exampleEl = document.getElementById('example')
const popover = new bootstrap.Popover(exampleEl, options)
通过仅将弹出框添加到传统上键盘可聚焦和交互的 HTML 元素（例如链接或表单控件）中，使弹出框对键盘和辅助技术用户保持可访问性。虽然其他 HTML 元素可以通过添加 来使可聚焦，但这可能会在键盘用户的非交互式元素上创建烦人且令人困惑的制表位，并且大多数辅助技术目前不会在这种情况下宣布弹出窗口。此外，不要仅仅依赖弹出窗口作为触发器，因为这将使键盘用户无法触发它们。tabindex="0"hover
使用该选项避免在弹出框中添加过多的内容。弹出框显示后，其内容将与具有属性的触发元素绑定，从而导致弹出框的所有内容作为一个长而不间断的流向辅助技术用户宣布。htmlaria-describedby
弹出框不管理键盘焦点顺序，它们在 DOM 中的位置可能是随机的，因此在添加交互元素（如表单或链接）时要小心，因为它可能会导致不合逻辑的焦点顺序或使弹出框内容本身完全无法访问键盘用户。如果必须使用这些元素，请考虑改用模式对话框。
选项
由于选项可以通过数据属性或 JavaScript 传递，因此您可以将选项名称附加到 ，如 。通过数据属性传递选项时，请确保将选项名称的大小写类型从“camelCase”更改为“kebab-case”。例如，使用 代替 。data-bs-data-bs-animation="{value}"data-bs-custom-class="beautifier"data-bs-customClass="beautifier"
从 Bootstrap 5.2.0 开始，所有组件都支持实验性保留数据属性，该属性可以将简单的组件配置作为 JSON 字符串容纳。当元素具有 和 属性时，最终值将是 ，并且单独的数据属性将覆盖 上给出的值。此外，现有数据属性能够容纳 JSON 值，例如 .data-bs-configdata-bs-config='{"delay":0, "title":123}'data-bs-title="456"title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'
最终配置对象是 、 的合并结果，其中最新给定的键值覆盖其他键值。data-bs-configdata-bs-js object
请注意，出于安全原因，不能使用数据属性提供 、 和 选项。sanitizesanitizeFnallowList
| 名字 | 类型 | 违约 | 描述 |
|---|---|---|---|
allowList | 对象 | 默认值 | 包含允许的标记和属性的对象。未显式允许的标记和属性将被内容清理器删除。 添加到此列表时要小心。有关更多信息，请参阅 OWASP 的跨站点脚本预防备忘单。 |
animation | 布尔 | true | 将 CSS 淡入淡出过渡应用于弹出框。 |
boundary | 字符串， 元素 | 'clippingParents' | Overflow 约束边界（仅适用于 Popper 的 preventOverflow 修饰符）。默认情况下，它可以接受 HTMLElement 引用（仅通过 JavaScript）。有关更多信息，请参阅 Popper 的 detectOverflow 文档。'clippingParents' |
container | 字符串、元素、假 | false | 将弹出框附加到特定元素。 例：。 此选项特别有用，因为它允许您将弹出框放置在文档流中靠近触发元素的位置 – 这将防止弹出框在窗口调整大小时从触发元素上浮动。container: 'body' |
content | 字符串， 元素， 函数 | '' | 弹出框的文本内容。如果给出了函数，则调用该函数时，其引用将设置为弹出框所附加的元素。this |
customClass | 字符串， 函数 | '' | 在弹出框显示时将其添加到弹出框中。请注意，除了模板中指定的任何类之外，还将添加这些类。要添加多个类，请用空格分隔它们：。您还可以传递一个函数，该函数应返回包含其他类名的单个字符串。'class-1 class-2' |
delay | number， 对象 | 0 | 显示和隐藏弹出框的延迟 （ms） – 不适用于手动触发器类型。如果提供了数字，则延迟将应用于隐藏/显示。对象结构为：。delay: { "show": 500, "hide": 100 } |
fallbackPlacements | 字符串， 数组 | ['top', 'right', 'bottom', 'left'] | 通过提供数组中的放置列表（按优先顺序）来定义后备放置。有关更多信息，请参阅 Popper 的行为文档。 |
html | 布尔 | false | 允许在弹出框中使用 HTML。如果为 true，则弹出框中的 HTML 标签将在弹出框中呈现。如果为 false，则属性将用于将内容插入 DOM。在处理用户生成的输入时，首选文本以防止 XSS 攻击。titleinnerText |
offset | 数字， 字符串， 函数 | [0, 8] | 弹出框相对于其目标的偏移量。您可以在数据属性中传递一个字符串，并带有逗号分隔的值，例如： 。当一个函数用于确定偏移量时，它被调用时，它包含 popper 位置、引用和 popper 矩形作为其第一个参数。触发元素 DOM 节点作为第二个参数传递。该函数必须返回一个包含两个数字的数组：skidding、distance。有关更多信息，请参阅 Popper 的偏移量文档。data-bs-offset="10,20" |
placement | 字符串， 函数 | 'right' | 如何定位弹出框：auto、top、bottom、left、right。指定后，它将动态地重新定向弹出框。当使用函数来确定位置时，调用该函数时，弹出框 DOM 节点作为其第一个参数，触发元素 DOM 节点作为第二个参数。上下文设置为弹出框实例。autothis |
popperConfig | 空， 对象， 函数 | null | 要更改 Bootstrap 的默认 Popper 配置，请参阅 Popper 的配置。当使用函数创建 Popper 配置时，它会使用包含 Bootstrap 默认 Popper 配置的对象调用。它可以帮助您使用默认值并将其与您自己的配置合并。该函数必须返回 Popper 的配置对象。 |
sanitize | 布尔 | true | 启用内容清理。如果为 true，则将对 、 和选项进行清理。templatecontenttitle 禁用内容清理时要小心。有关详细信息，请参阅 OWASP 的跨站点脚本预防备忘单。仅由禁用内容清理引起的漏洞不被视为 Bootstrap 安全模型的范围内。 |
sanitizeFn | null，函数 | null | 提供替代内容清理功能。如果您更喜欢使用专用库来执行清理，这会很有用。 |
selector | 字符串，假 | false | 如果提供了选择器，则弹出框对象将委托给指定的目标。在实践中，这也用于将弹出框应用于动态添加的 DOM 元素（支持）。请参阅此问题和信息丰富的示例。注意：属性不得用作选择器。jQuery.ontitle |
template | 字符串 | '<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>' | 创建弹出框时要使用的基本 HTML。弹出框将被注入到 .弹出框将被注入到 . 将成为弹出框的箭头。最外层的包装器元素应该具有类和 .title.popover-headercontent.popover-body.popover-arrow.popoverrole="tooltip" |
title | 字符串， 元素， 函数 | '' | 弹出框标题。如果给定了一个函数，则调用该函数时，其引用设置为弹出框所附加的元素。this |
trigger | 字符串 | 'click' | 弹出框的触发方式：点击、悬停、对焦、手动。您可以传递多个触发器;用空格将它们分隔开来。 表示弹出框将通过 和 方法以编程方式触发;此值不能与任何其他触发器组合使用。 它本身将导致无法通过键盘触发的弹出框，并且仅当存在为键盘用户传达相同信息的替代方法时才应使用。'manual'.popover('show').popover('hide').popover('toggle')'hover' |
将函数与popperConfig
const popover = new bootstrap.Popover(element, {
popperConfig(defaultBsPopperConfig) {
// const newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
方法
所有 API 方法都是异步的，并启动转换。它们在转换开始后立即返回给调用方，但在转换结束之前。此外，对转换组件的方法调用将被忽略。在我们的 JavaScript 文档中了解更多信息。
| 方法 | 描述 |
|---|---|
disable | 删除显示元素弹出框的功能。只有重新启用弹出框后才能显示。 |
dispose | 隐藏并销毁元素的弹出框（删除 DOM 元素上存储的数据）。使用委托的弹出框（使用选择器选项创建）不能在后代触发器元素上单独销毁。 |
enable | 使元素的弹出窗口能够显示。弹出框默认启用。 |
getInstance | 静态方法，允许您获取与 DOM 元素关联的弹出窗口实例。 |
getOrCreateInstance | 静态方法，允许您获取与 DOM 元素关联的弹出框实例，或创建一个新实例以防它未初始化。 |
hide | 隐藏元素的弹出框。在弹出窗口实际隐藏之前（即事件发生之前）返回给调用者。这被认为是弹出框的“手动”触发。hidden.bs.popover |
setContent | 提供了一种在初始化后更改弹出框内容的方法。 |
show | 显示元素的弹出框。在弹出窗口实际显示之前（即事件发生之前）返回给调用者。这被认为是弹出框的“手动”触发。标题和内容长度均为零的弹出框永远不会显示。shown.bs.popover |
toggle | 切换元素的弹出框。在弹出框实际显示或隐藏之前（即在 or 事件发生之前）返回给调用者。这被认为是弹出框的“手动”触发。shown.bs.popoverhidden.bs.popover |
toggleEnabled | 切换元素弹出框的显示或隐藏功能。 |
update | 更新元素弹出框的位置。 |
// getOrCreateInstance example
const popover = bootstrap.Popover.getOrCreateInstance('#example') // Returns a Bootstrap popover instance
// setContent example
popover.setContent({
'.popover-header': 'another title',
'.popover-body': 'another content'
})
该方法接受一个参数，其中每个属性键都是弹出框模板中的有效选择器，并且每个相关的属性值可以是 | | |setContentobjectstringstringelementfunctionnull
事件
| 事件 | 描述 |
|---|---|
hide.bs.popover | 调用实例方法后，会立即触发此事件。hide |
hidden.bs.popover | 当弹出框完成对用户隐藏时，将触发此事件（将等待 CSS 转换完成）。 |
inserted.bs.popover | 当弹出框模板已添加到 DOM 时，此事件在事件发生后触发。show.bs.popover |
show.bs.popover | 调用实例方法时，此事件会立即触发。show |
shown.bs.popover | 当弹出框对用户可见时，将触发此事件（将等待 CSS 转换完成）。 |
const myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', () => {
// do something...
})