弹出框

用于在网站上的任何元素中添加 Bootstrap 弹出框（如 iOS 中所见）的文档和示例。

本页目录

概览

使用弹出框插件时需要注意的事项：

弹出层依赖于第三方库波普用于定位。你必须包括 popper.min.js 之前 bootstrap.js，或者使用一个 bootstrap.bundle.min.js 其中包含Popper。
泡芙需要弹出框插件作为依赖。
弹出窗口出于性能原因是可选择加入的，所以 你必须自己初始化它们.
零长度 title 和 content 值永远不会显示弹出框。
指定 container: 'body' 以避免在更复杂的组件中（如我们的输入组、按钮组等）出现渲染问题。
在隐藏元素上触发弹出框将不起作用。
泡芙用于 .disabled 或 disabled 元素必须在一个包装元素上被触发。
当从跨多行的锚点触发时，弹出框将位于锚点整体宽度的中央。使用 .text-nowrap 在你的 <a>以避免这种行为。
弹出框必须在其对应的元素从 DOM 中移除之前被隐藏。
弹出框可以通过位于 Shadow 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-title 设置，主体内容通过 data-bs-content 设置。

在你的 HTML 中可以自由使用 title 或 data-bs-title。当使用 title 时，Popper 会在元素渲染时自动将其替换为 data-bs-title。

HTML

<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 可以更改方向。

HTML

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

当父元素上有一些样式干扰弹出框时，你需要指定一个自定义 container，以便弹出框的 HTML 出现在该元素内。这在响应式表格、输入组等情况下很常见。

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

另一种你需要设置明确自定义 container 的情况是在模态框内的弹出框，以确保弹出框本身被附加到模态框中。这对于包含交互元素的弹出框尤其重要——模态框会限制焦点，因此除非弹出框是模态框的子元素，否则用户将无法聚焦或激活这些交互元素。

const popover = new bootstrap.Popover('.example-popover', {
  container: '.modal-body'
})

自定义弹出框

在 v5.2.0 中添加

你可以使用 CSS 变量来自定义弹出框的外观。我们使用 data-bs-custom-class="custom-popover" 设置一个自定义类来限定我们的自定义外观，并使用它来覆盖一些本地 CSS 变量。

site/src/scss/_组件示例.scss

.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;
}

HTML

<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 才能实现跨浏览器和跨平台的正确行为。 你只能使用 <a> 元素，而不能使用 <button>，并且必须包含一个 tabindex。

可关闭弹出框

HTML

<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"，这样弹出框可以作为即时视觉反馈显示给你的用户，因为他们可能不会期望去点击一个被禁用的元素。

HTML

<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 变量方法的一部分，弹出框现在在 .popover 上使用本地 CSS 变量，以增强实时自定义能力。CSS 变量的值通过 Sass 设置，因此仍然支持 Sass 自定义。

scss/_popover.scss

--#{$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 变量

scss/_variables.scss

$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 作为弹出框的触发器，因为这会使键盘用户无法触发它们。

避免在弹出框中添加过多内容 html 选项。一旦弹出框显示，它们的内容将与触发元素绑定 aria-describedby 属性，导致所有弹出内容作为一条长且连续的流向辅助技术用户进行播报。

弹出框不会管理键盘焦点顺序，并且它们在 DOM 中的位置可能是随机的，因此在添加交互元素（如表单或链接）时要小心，因为这可能导致焦点顺序不合逻辑，或者使弹出框内容对键盘用户完全无法访问。在必须使用这些元素的情况下，可以考虑使用模态框代替。

选项

由于选项可以通过数据属性或 JavaScript 传递，你可以将选项名称附加到 data-bs-，就像在 data-bs-animation="{value}" 中一样。确保在通过数据属性传递选项时，将选项名称的大小写类型从“camelCase”更改为“kebab-case”。例如，使用 data-bs-custom-class="beautifier" 而不是 data-bs-customClass="beautifier"。

从 Bootstrap 5.2.0 开始，所有组件都支持一个 实验性的保留数据属性 data-bs-config，它可以用作存放简单组件配置的 JSON 字符串。当一个元素同时拥有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 属性时，最终的 title 值将会是 456，且单独的数据属性将覆盖 data-bs-config 上给定的值。此外，现有的数据属性也能够存放如 data-bs-delay='{"show":0,"hide":150}' 的 JSON 值。

最终的配置对象是data-bs-config、data-bs-和js object合并的结果，其中最新提供的键值会覆盖其他键值。

请注意，出于安全原因，sanitize、sanitizeFn和allowList选项不能通过数据属性提供。

名称	类型	默认值	描述
`allowList`	object	默认值	一个包含允许标签和属性的对象。那些未明确允许的将被移除内容净化器. 在向此列表添加内容时要谨慎。参考 OWASP 跨站脚本防护备忘单欲了解更多信息。
`animation`	boolean	`true`	对弹出框应用 CSS 淡入淡出过渡效果。
`boundary`	字符串，元素	`'clippingParents'`	弹出框的溢出约束边界（仅适用于 Popper 的 preventOverflow 修改器）。默认情况下，它是 `'clippingParents'` 并且可以接受一个 HTMLElement 引用（仅通过 JavaScript）。有关更多信息，请参阅 Popper 的 detectOverflow 文档.
`container`	字符串，元素，假	`false`	将弹出框附加到特定元素。示例： `container: 'body'`此选项特别有用，因为它允许你将弹出框在文档流中靠近触发元素的位置进行定位——这将防止在窗口调整大小时弹出框脱离触发元素飘移。
`content`	字符串，元素，函数	`''`	弹出框的文本内容。如果提供了一个函数，将使用它调用 `this` 引用设置为弹出框所附加的元素。
`customClass`	字符串，函数	`''`	在弹出框显示时添加类。请注意，这些类将会在模板中指定的任何类之外添加。要添加多个类，请用空格分隔： `'class-1 class-2'`你还可以传入一个函数，该函数应返回一个包含额外类名的单个字符串。
`delay`	数字, 对象	`0`	延迟显示和隐藏弹出框（毫秒）——不适用于手动触发类型。如果提供了一个数字，延迟将同时应用于隐藏/显示。对象结构为： `delay: { "show": 500, "hide": 100 }`.
`fallbackPlacements`	字符串，数组	`['top', 'right', 'bottom', 'left']`	通过在数组中提供位置列表（按优先顺序）来定义回退位置。更多信息请参考 Popper 的文档。行为文档.
`html`	boolean	`false`	允许在弹出框中使用 HTML。如果为真，弹出框中的 HTML 标签将 `title` 将在弹出框中显示。如果为 false， `innerText` 该属性将用于将内容插入到 DOM 中。在处理用户生成的输入时，优先使用文本防止 XSS 攻击.
`offset`	数字，字符串，函数	`[0, 8]`	弹出框相对于其目标的偏移量。你可以在数据属性中传递一个以逗号分隔的字符串，如： `data-bs-offset="10,20"`当使用函数来确定偏移量时，它会以一个包含 popper 位置、参考元素和 popper 矩形的对象作为第一个参数进行调用。触发元素的 DOM 节点作为第二个参数传递。该函数必须返回一个包含两个数字的数组：打滑, 距离有关更多信息，请参阅Popper的著作补偿文档.
`placement`	字符串，函数	`'right'`	如何定位弹出框：自动、上、下、左、右。当 `auto` 如果指定，它将动态重新定位弹出框。当使用函数来确定位置时，该函数的第一个参数是弹出框的 DOM 节点，第二个参数是触发元素的 DOM 节点。 `this` 上下文被设置为弹出框实例。
`popperConfig`	null，对象，函数	`null`	要更改 Bootstrap 的默认 Popper 配置，请参阅 Popper的配置当使用函数来创建 Popper 配置时，它会被一个包含 Bootstrap 默认 Popper 配置的对象调用。它帮助你使用并合并默认配置与自己的配置。该函数必须返回一个 Popper 的配置对象。
`sanitize`	boolean	`true`	启用内容净化. 如果是真的， `template`, `content` 和 `title` 选项将被清理。在禁用内容清理时要谨慎。参考 OWASP 跨站脚本防护备忘单欲了解更多信息。仅因禁用内容清理而导致的漏洞不被视为 Bootstrap 安全模型的范围内。
`sanitizeFn`	空值，函数	`null`	提供一个替代方案内容净化功能。如果你更喜欢使用专用库来执行清理，这可能会很有用。
`selector`	字符串, 假	`false`	如果提供了选择器，popover 对象将被委托给指定的目标。实际上，这也用于将 popover 应用于动态添加的 DOM 元素。`jQuery.on` 支持)。参见这个问题. 注意: `title` 属性不得用作选择器。
`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` 类和 `role="tooltip"`.
`title`	字符串，元素，函数	`''`	弹出框标题。如果提供了一个函数，它将被调用并传入它的 `this` 引用设置为弹出框所附加的元素。
`trigger`	string	`'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 元素上存储的数据）。使用委托的弹出框（通过创建时使用）这 `selector` 选项) 不能在后代触发元素上单独销毁。
`enable`	赋予元素的弹出框显示的能力。弹出框默认启用。
`getInstance`	静态一种允许你获取与 DOM 元素关联的弹出实例的方法。
`getOrCreateInstance`	静态一种方法，允许你获取与 DOM 元素关联的弹出框实例，或者在未初始化的情况下创建一个新的实例。
`hide`	隐藏元素的弹出框。在弹出窗口实际被隐藏之前返回给调用者（即在……之前 `hidden.bs.popover` 事件发生）。这被视为弹出框的“手动”触发。
`setContent`	提供了一种在初始化后更改弹出框内容的方法。
`show`	显示元素的弹出框。在弹出窗口实际显示之前返回给调用者（即在……之前 `shown.bs.popover` 事件发生）。这被视为弹出框的“手动”触发。标题和内容都为空的弹出框永远不会显示。
`toggle`	切换元素的弹出框。在弹出层实际显示或隐藏之前返回给调用者（即在……之前 `shown.bs.popover` 或 `hidden.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'
})

setContent 方法接受一个 object 参数，其中每个属性键都是弹出框模板中有效的 string 选择器，每个相关的属性值可以是 string | element | function | null

事件

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

const myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', () => {
  // do something...
})

弹出框

概览

示例

启用弹出框

现场演示

四个方向

自定义 container

自定义弹出框

在下一次点击时关闭

禁用的元素

CSS

变量

Sass 变量

用法

选项

单个弹出框的数据属性

在 popperConfig 上使用函数

方法

事件

自定义 `container`

在 `popperConfig` 上使用函数