弹出框

有关将Bootstrap弹出框（如 iOS 中的弹出框）添加到站点上的任何元素的文档和示例。

当前页

概述

使用弹出框插件时要了解的事项：

弹出框依靠第三方库 Popper 进行定位。您必须在bootstrap.js之前包含popper.min.js，或者使用一个包含Popper的bootstrap.bundle.min.js。
弹出框需要 popover plugin 作为依赖项。
出于性能原因，弹出框是选择加入的，因此您必须自己初始化它们。
长度为零的title和content值永远不会显示弹出框。
指定container: 'body'以避免在更复杂的组件（如我们的输入组、按钮组等）中呈现问题。
在隐藏元素上触发弹出框将不起作用。
必须在包装器元素上触发 .disabled或 disabled元素的弹出框。
当从跨多行换行的锚点触发时，弹出框将在锚点的总宽度之间居中。在<a>上使用.text-nowrap以避免此行为。
在从 DOM 中删除相应的元素之前，必须隐藏弹出框。
由于阴影DOM中的元素，可以触发弹出框。

默认情况下，此组件使用内置内容清理器，该清理程序会去除未明确允许的任何 HTML 元素。请参阅我们的 JavaScript 文档中的 sanitizer 部分了解更多详情。

此组件的动画效果取决于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的另一种情况是 modeddialog 中的弹出框，以确保弹出窗口本身附加到模态中。这对于包含交互式元素的弹出框尤其重要 - 模式对话框将捕获焦点，因此除非弹出框是模式的子元素，否则用户将无法聚焦或激活这些交互式元素。

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

自定义弹出框

Added in v5.2.0

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

site/assets/scss/_component-examples.scss

.custom-popover {
  --bs-popover-max-width: 200px;
  --bs-popover-border-color: var(--bs-primary);
  --bs-popover-header-bg: var(--bs-primary);
  --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’。

Dismissible popover

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

变量

Added in 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:                $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 元素（如链接或表单控件）中，使键盘和辅助技术用户能够访问弹出框。虽然可以通过添加tabindex="0"来使其他HTML元素可聚焦，但这可能会在非交互式元素上为键盘用户创建烦人和令人困惑的制表位，并且大多数辅助技术目前不会在这种情况下宣布弹出框。此外，不要仅仅依靠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 上给出的值。此外，现有的数据属性能够容纳JSON值，如data-bs-delay='{"show":0,"hide":150}'。

请注意，出于安全原因，无法使用数据属性提供sanitize、sanitizeFn和allowList选项。

名称	类型	默认值	描述
`allowList`	object	Default value	包含允许的属性和标记的对象。
`animation`	boolean	`true`	将 CSS 淡入淡出过渡应用于弹出框。
`boundary`	string, element	`'clippingParents'`	弹出框的溢出约束边界（仅适用于波普尔的防止溢出修饰符）。默认情况下，它是`'clippingParents'`，可以接受 HTMLElement 引用（仅通过 JavaScript）。有关更多信息，请参阅 Popper 的 detectOverflow docs。
`container`	string, element, false	`false`	将弹出框追加到特定元素。示例： `container: 'body'`。此选项特别有用，因为它允许您将弹出框放置在文档流中靠近触发元素的位置 - 这将防止弹出框在窗口调整大小期间从触发元素上浮动。
`content`	string, element, function	`''`	默认内容值（如果`data-bs-content`属性不存在）。如果给定了一个函数，则将调用该函数，并将其`this`引用设置为弹出框附加到的元素。
`customClass`	string, function	`''`	在弹出窗口显示时向其添加类。请注意，除了模板中指定的任何类之外，还将添加这些类。要添加多个类，请用空格分隔它们：`'class-1 class-2'`。还可以传递一个函数，该函数应返回包含其他类名的单个字符串。
`delay`	number, object	`0`	延迟显示和隐藏弹出框（ms） - 不适用于手动触发器类型。如果提供了数字，则会对隐藏/显示应用延迟。对象结构为：`delay: { "show": 500, "hide": 100 }`。
`fallbackPlacements`	string, array	`['top', 'right', 'bottom', 'left']`	通过提供数组中的展示位置列表（按优先顺序）来定义回退展示位置。有关更多信息，请参阅 Popper 的行为文档。
`html`	boolean	`false`	允许在弹出框中显示 HTML。如果为 true，则弹出框 `title`中的 HTML 标记将在弹出框中呈现。如果为 false，则`innerText`属性将用于将内容插入到 DOM 中。如果您担心 XSS 攻击，请使用文本。
`offset`	number, string, function	`[0, 0]`	弹出框相对于其目标的偏移量。您可以在数据属性中传递带有逗号分隔值的字符串，例如： `data-bs-offset="10,20"`。当函数用于确定偏移量时，将使用包含波普尔位置、引用和波普尔矩形的对象作为其第一个参数来调用该函数。触发元素 DOM 节点作为第二个参数传递。该函数必须返回一个包含两个数字的数组：skidding、distance。有关更多信息，请参阅 Popper 的偏移文档。
`placement`	string, function	`'top'`	如何定位弹出框：自动、顶部、底部、左侧、右侧。指定 `auto`时，它将动态地重新定向弹出框。当一个函数用于确定放置时，它被调用，弹出的 DOM 节点作为其第一个参数，触发元素 DOM 节点作为其第二个参数。 `this`上下文设置为弹出框实例。
`popperConfig`	null, object, function	`null`	要更改 Bootstrap 的默认 Popper 配置，请参阅 Popper 的配置。当函数用于创建 Popper 配置时，将使用包含 Bootstrap 的默认 Popper 配置的对象调用该函数。它可以帮助您使用默认值并将其与您自己的配置合并。该函数必须返回 Popper 的配置对象。
`sanitize`	boolean	`true`	启用或禁用清理。如果激活`'template'`， `'content'`和 `'title'`选项将被清理。
`sanitizeFn`	null, function	`null`	在这里，您可以提供自己的消毒功能。如果您希望使用专用库来执行清理，这会很有用。
`selector`	string, false	`false`	如果提供了选择器，则会将弹出框对象委派给指定的目标。在实践中，这也用于将弹出框应用于动态添加的 DOM 元素（`jQuery.on`支持）。请参阅 this issue 和 a informatative example。注意：`title`属性不得用作选择器。
`template`	string	`'<div class="popover" role="popover"><div class="popover-arrow"></div><div class="popover-inner"></div></div>'`	创建弹出框时要使用的基本 HTML。弹出框的`title`将被注入到`.popover-inner`中。 `.popover-arrow`将成为弹出框的箭头。最外面的包装元素应该有`.popover`类和`role="popover"`。
`title`	string, element, function	`''`	默认标题值（如果`title`属性不存在）。如果给定了一个函数，则将调用该函数，并将其`this`引用设置为弹出框附加到的元素。
`trigger`	string	`'hover focus'`	如何触发弹出框：单击、悬停、聚焦、手动。您可以传递多个触发器;用空格分隔它们。`'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`	Static 方法，它允许您获取与 DOM 元素关联的弹出框实例。
`getOrCreateInstance`	Static 方法，它允许您获取与 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
myPopover.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`	当弹出框模板已添加到 DOM 时，此事件在`show.bs.popover`事件之后触发。
`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`一起使用