View on GitHub

弹出提示框（Popovers）

为网站上的任何元素添加 Bootstrap 弹出窗口（如 iOS 中的弹出窗口）的文档和示例。

On this page

概述

使用弹出窗口插件的注意事项

Popovers 依靠第三方库 Popper 进行定位。您必须在 bootstrap.js 前包含 popper.min.js，或者使用包含 Popper 的 bootstrap.bundle.min.js。
弹出窗口需要依赖 popover 插件。
出于性能考虑，弹出窗口是选择性的，因此 您必须自行初始化 。
长度为零的 “标题 ”和 “内容 ”值将不会显示弹出窗口。
指定 container: 'body'，以避免在更复杂的组件（如输入组、按钮组等）中出现渲染问题。
在隐藏元素上触发弹出窗口将不起作用。
.disabled or disabled 的弹出窗口必须在包装元素上触发。
当从多行缠绕的锚点触发时，弹出窗口将在锚点的整体宽度之间居中。在<a>上使用.text-nowrap 可避免这种行为。
弹出窗口必须在相应元素从 DOM 中移除之前隐藏。
Popovers 可以通过阴影 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 的情况是模态对话框中的弹出窗口，以确保弹出窗口本身附加到模态对话框中。这对于包含交互式元素的弹出窗口尤为重要–模式对话框会捕获焦点，因此除非弹出窗口是模式对话框的子元素，否则用户将无法聚焦或激活这些交互式元素。

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

自定义弹出窗（popovers）

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(--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。

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"，这样弹出式触发器就会立即向用户提供视觉反馈，因为他们可能不会想到要_click_禁用的元素。

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:                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 元素（如链接或表单控件）上添加弹出窗口，以保持键盘和辅助技术用户 可访问弹出窗口。虽然可以通过添加 tabindex=“0” 使其他 HTML 元素成为可聚焦元素，但这会在非交互式元素上为键盘用户创建恼人且令人困惑的制表符停止点，而且大多数辅助技术目前都不会在这种情况下显示弹出窗口。此外，不要仅依赖 hover 作为弹出窗口的触发器，否则键盘用户将无法触发弹出窗口。

使用 html 选项可避免在弹出窗口中添加过多内容。弹出窗口一旦显示，其内容就会通过 aria-describedby 属性与触发元素绑定，从而使弹出窗口的所有内容都会作为一个不间断的长流向辅助技术用户公布。

弹出窗口不会管理键盘焦点顺序，其在 DOM 中的位置也可能是随机的，因此在添加交互式元素（如表单或链接）时一定要小心，因为这可能会导致焦点顺序不合逻辑，或使键盘用户完全无法访问弹出窗口内容本身。如果您必须使用这些元素，请考虑使用模式对话框来代替。

选项

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

从 Bootstrap 5.2.0 开始，所有组件都支持一个实验性预留data 属性 data-bs-config ，它可以将简单的组件配置以 JSON 字符串的形式存放。当一个元素具有data-bs-config='{“delay”:0, “title”:123}' 和 data-bs-title=“456” 属性时，最终的title值将是456，而单独的data 属性将覆盖data-bs-config上给出的值。此外，现有的data 属性还能容纳 JSON 值，如 data-bs-delay='{“show”:0, “hide”:150}'。

最终配置对象是 data-bs-config、data-bs- 和 js object 的合并结果，其中最新给定的键值优先于其他键值。

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

Name	Type	Default	Description
`allowList`	object	Default value	包含允许属性和标记的对象。
`animation`	boolean	`true`	为弹出窗口应用 CSS 淡入淡出过渡。
`boundary`	string, element	`'clippingParents'`	弹出窗口的溢出约束边界（仅适用于 Popper 的 preventOverflow 修改器）。默认情况下，它是"‘clippingParents’"，并且可以接受 HTMLElement 引用（仅通过 JavaScript）。更多信息请参阅 Popper 的 detectOverflow docs。
`container`	string, element, false	`false`	将弹出窗口添加到特定元素。例如：`container: 'body'`。该选项特别有用，因为它允许你将弹出窗口定位在文档流中靠近触发元素的位置- 这将防止弹出窗口在窗口调整大小时从触发元素上飘走。
`content`	string, element, function	`''`	弹出窗口的文本内容。如果给定了一个函数，则在调用该函数时会将其 `this` 引用设置为弹出窗口所连接的元素。
`customClass`	string, function	`''`	在弹出窗口显示时添加类。请注意，这些类是在模板中指定的类之外添加的。要添加多个类，请用空格分隔：`'class-1 class-2'`。您也可以传递一个函数，该函数将返回一个包含其他类名的字符串。
`delay`	number, object	`0`	显示和隐藏弹出窗口的延迟（毫秒）-不适用于手动触发类型。如果提供了数字，则隐藏/显示时都会应用延迟。对象结构如下: `delay: { "show": 500, "hide": 100 }`.
`fallbackPlacements`	string, array	`['top', 'right', 'bottom', 'left']`	通过提供数组中的位置列表（按优先级排序）来定义后备位置。更多信息请参阅 Popper 的 behavior docs。
`html`	boolean	`false`	允许在弹出窗口中使用 HTML。如果为 “true”，弹出窗口的 “title” 中的 HTML 标记将在弹出窗口中渲染。如果为假，将使用 `innerText` 属性在 DOM 中插入内容。如果担心 XSS 攻击，请使用文本。
`offset`	number, string, function	`[0, 0]`	弹出窗口相对于目标的偏移量。您可以在数据属性中传递一个以逗号分隔的字符串，例如 `data-bs-offset="10,20"`. 当使用函数来确定偏移量时，它的第一个参数是一个包含弹出窗口位置、引用和弹出窗口矩形的对象。触发元素 DOM 节点作为第二个参数传递。函数必须返回一个包含两个数字的数组：滑动、距离。更多信息请参阅 Popper 的 offset docs。
`placement`	string, function	`'top'`	如何定位弹出窗口：自动、上、下、左、右。指定 `auto` 时，将动态调整弹出窗口的方向。如果使用函数来确定弹出窗口的位置，则会以弹出窗口 DOM 节点作为第一个参数，以触发元素 DOM 节点作为第二个参数来调用该函数。`this` 上下文设置为 popover 实例。
`popperConfig`	null, object, function	`null`	要更改 Bootstrap 的默认 Popper 配置，请参阅 Popper’s configuration。当使用函数创建 Popper 配置时，会调用一个包含 Bootstrap 默认 Popper 配置的对象。它可以帮助您使用默认配置并将其与自己的配置合并。函数必须返回一个 Popper 配置对象。
`sanitize`	boolean	`true`	启用或禁用清理。如果激活，`'template'`、`'content'` 和`'title'` 选项将被清理。
`sanitizeFn`	null, function	`null`	在这里，您可以提供自己的 sanitize 函数。如果您更喜欢使用专门的库来执行 sanitize，这将非常有用。
`selector`	string, false	`false`	如果提供了选择器，弹出窗口对象将被委托给指定的目标。在实践中，这也用于将弹出窗口应用于动态添加的 DOM 元素（支持 `jQuery.on`）。请参见 this issue 和 an informative example. 注意： `title` 属性不得用作选择器。
`template`	string	`'<div class="popover" role="tooltip"><div class="popover-arrow"></div><div class="popover-inner"></div></div>'`	创建弹出窗口时使用的基本 HTML。弹出窗口的`title` 将注入`.popover-inner`。`popover-arrow` 将成为弹出窗口的箭头。最外层的包装元素应具有 `.popover` 类和 `role="tooltip"`。
`title`	string, element, function	`''`	弹出窗口标题。如果给定了一个函数，则在调用该函数时会将其 `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 文档

Method	Description
`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
popover.setContent({
  '.popover-header': 'another title',
  '.popover-body': 'another content'
})

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

事件

Event	Description
`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...
})

弹出提示框（Popovers）

概述

示例

启用弹出窗口

在线演示

四个方向

自定义 container

自定义弹出窗（popovers）

下一次点击时解除

禁用元素

CSS

变量

Sass 变量

用法

选项

单个弹出窗口的数据属性

将函数与 popperConfig 结合使用

方法

事件

自定义 `container`

将函数与 `popperConfig` 结合使用