Skip to main content Skip to docs navigation
在GitHub查看

悬浮提示

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

在此页

概述

使用 popover 插件时的注意事项：

  • Popovers依赖第三方库Popper进行定位。你必须在之前包含popper.min.jsbootstrap.js，或者使用一个bootstrap.bundle.min.js包含 Popper 的。
  • Popovers 需要popover 插件作为依赖项。
  • 出于性能原因，弹出窗口是可选的，因此您必须自己初始化它们。
  • 零长度title和content值永远不会显示弹出窗口。
  • 指定container: 'body'以避免在更复杂的组件（如我们的输入组、按钮组等）中出现渲染问题。
  • 在隐藏元素上触发弹出窗口将不起作用。
  • .disabled或元素的弹出窗口disabled必须在包装元素上触发。
  • 当从环绕多行的锚点触发时，弹出窗口将在锚点的总宽度之间居中。.text-nowrap在你的 s 上使用<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-title，正文内容通过 设置data-bs-content。

随意使用title或data-bs-title在您的 HTML 中。当使用时，Popper 会在渲染元素时 title自动替换它。data-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

当您的父元素上有一些样式会干扰弹出框时，您需要指定一个自定义样式，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 变量。

.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;
}
网页格式 
<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触发器在用户下次单击与切换元素不同的元素时关闭弹出窗口。

下次点击时关闭所需的特定标记

为了正确的跨浏览器和跨平台行为，您必须使用<a>标签，而不是<button>标签，并且您还必须包含一个tabindex属性。

可消除的弹出窗口
网页格式 
<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 变量.popover来增强实时自定义。CSS 变量的值是通过 Sass 设置的，因此仍然支持 Sass 自定义。

  --#{$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:                $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 元素（例如<span>s）成为可聚焦的tabindex="0"，但这会为键盘用户在非交互元素上添加潜在的烦人和混乱的制表位，并且大多数辅助技术目前不会在这种情况下宣布弹出窗口的内容. 此外，不要仅仅依赖于hover作为弹出窗口的触发器，因为这将使键盘用户无法触发它们。

虽然您可以使用该选项在弹出窗口中插入丰富的结构化 HTML html，但我们强烈建议您避免添加过多的内容。弹出窗口当前的工作方式是，一旦显示，它们的内容就会绑定到具有aria-describedby属性的触发元素。因此，弹出窗口的全部内容将作为一个长的、不间断的流向辅助技术用户公布。

此外，虽然还可以在弹出窗口中包含交互式控件（例如表单元素或链接）（通过将这些元素添加到allowList允许的属性和标签中），但请注意，当前弹出窗口不管理键盘焦点顺序。当键盘用户打开弹出窗口时，焦点仍停留在触发元素上，并且由于弹出窗口通常不会立即跟随文档结构中的触发器，因此无法保证向前移动/按下Tab会将键盘用户移动到弹出框本身。简而言之，简单地向弹出窗口添加交互式控件可能会使键盘用户和辅助技术用户无法访问/无法使用这些控件，或者至少会导致不合逻辑的整体焦点顺序。在这些情况下，请考虑改用模态对话框。

选项

由于可以通过数据属性或 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 目的 默认值 包含允许的属性和标签的对象。
animation 布尔值 true 将 CSS 淡入淡出过渡应用于弹出窗口。
boundary 字符串，元素 'clippingParents' popover 的溢出约束边界（仅适用于 Popper 的 preventOverflow 修饰符）。默认情况下，它'clippingParents'可以接受 HTMLElement 引用（仅通过 JavaScript）。有关详细信息，请参阅 Popper 的detectOverflow 文档。
container 字符串、元素、假 false 将弹出窗口附加到特定元素。例子：container: 'body'。此选项特别有用，因为它允许您将弹出窗口定位在触发元素附近的文档流中 - 这将防止弹出窗口在调整窗口大小时从触发元素上移开。
content 字符串、元素、函数 '' data-bs-content如果属性不存在，则为默认内容值。如果给出了一个函数，它将被调用，其this引用设置为弹出窗口附加到的元素。
customClass 字符串、函数 '' 显示时将类添加到弹出窗口。请注意，除了模板中指定的任何类之外，还将添加这些类。要添加多个类，请用空格分隔它们：'class-1 class-2'。您还可以传递一个函数，该函数应返回包含其他类名的单个字符串。
delay 数字，对象 0 延迟显示和隐藏弹出框（毫秒）——不适用于手动触发类型。如果提供了数字，延迟将应用于隐藏/显示。对象结构是：delay: { "show": 500, "hide": 100 }.
fallbackPlacements 字符串，数组 ['top', 'right', 'bottom', 'left'] 通过提供数组中的展示位置列表（按优先顺序）来定义后备展示位置。有关更多信息，请参阅 Popper 的行为文档。
html 布尔值 false 在弹出窗口中允许 HTML。如果为 true，弹出窗口中的 HTML 标记title将在弹出窗口中呈现。如果为 false，innerText属性将用于将内容插入 DOM。如果您担心 XSS 攻击，请使用文本。
offset 数字、字符串、函数 [0, 0] 弹出框相对于其目标的偏移量。您可以使用逗号分隔值在数据属性中传递一个字符串，例如：data-bs-offset="10,20"。当一个函数被用来确定偏移量时，它被调用时带有一个包含 popper 位置、引用和 popper rect 的对象作为它的第一个参数。触发元素 DOM 节点作为第二个参数传递。该函数必须返回一个包含两个数字的数组：skidding和distance。有关更多信息，请参阅 Popper 的偏移量文档。
placement 字符串、函数 'top' 如何定位弹出窗口：自动、顶部、底部、左侧、右侧。指定时auto，它将动态重新定向弹出窗口。当一个函数被用来确定位置时，它被调用，弹出 DOM 节点作为它的第一个参数，触发元素 DOM 节点作为它的第二个参数。this上下文设置为弹出窗口实例。
popperConfig 空，对象，函数 null 要更改 Bootstrap 的默认 Popper 配置，请参阅Popper 的配置。当一个函数被用来创建 Popper 配置时，它被调用一个包含 Bootstrap 默认 Popper 配置的对象。它可以帮助您使用默认设置并将其与您自己的配置合并。该函数必须返回 Popper 的配置对象。
sanitize 布尔值 true 启用或禁用清理。如果激活'template'，选项将被清除'content'。'title'
sanitizeFn 空，功能 null 您可以在此处提供自己的清理功能。如果您更喜欢使用专用库来执行清理，这会很有用。
selector 字符串，假 false 如果提供了选择器，弹出对象将被委托给指定的目标。实际上，这也用于将弹出窗口应用于动态添加的 DOM 元素（jQuery.on支持）。请参阅此问题和一个信息示例。注意：title属性不得用作选择器。
template 细绳 '<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 字符串、元素、函数 '' title如果属性不存在，则为默认标题值。如果给出了一个函数，它将被调用，其this引用设置为弹出窗口附加到的元素。
trigger 细绳 '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 允许您获取与 DOM 元素关联的弹出窗口实例的静态方法。
getOrCreateInstance 允许您获取与 DOM 元素相关联的弹出窗口实例的静态方法，或者在未初始化的情况下创建一个新的弹出窗口实例。
hide 隐藏元素的弹出窗口。在弹出窗口实际被隐藏之前返回给调用者（即在hidden.bs.popover事件发生之前）。这被认为是弹出窗口的“手动”触发。
setContent 提供一种在初始化后更改弹出窗口内容的方法。
show 显示元素的弹出窗口。在弹出窗口实际显示之前（即事件发生之前）返回给调用者。shown.bs.popover这被认为是弹出窗口的“手动”触发。永远不会显示标题和内容均为零长度的弹出框。
toggle 切换元素的弹出窗口。在弹出窗口实际显示或隐藏之前返回给调用者（即在shown.bs.popoverorhidden.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 show.bs.popover当 popover 模板被添加到 DOM 时，该事件将在该事件之后触发。
show.bs.popover show调用实例方法时会立即触发此事件。
shown.bs.popover 当弹出窗口对用户可见时会触发此事件（将等待 CSS 转换完成）​​。 
const myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', () => {
  // do something...
})