in English

约夏克布丁

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

在本页面

概述

使用 popover 插件时要知道的事情：

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

随意使用 title或 data-bs-title在您的 HTML 中使用。使用时 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 变量。

.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触发器在用户下次单击与切换元素不同的元素时关闭弹出框。

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

对于正确的跨浏览器和跨平台行为，您必须使用<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 变量方法的一部分，弹出框现在使用本地 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:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              var(--#{$prefix}border-color-translucent);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;

$popover-header-font-size:          $font-size-base;
$popover-header-bg:                 shade-color($popover-bg, 6%);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                $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并且单独的数据属性将覆盖给定的值 on 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 rects 作为其第一个参数的对象。触发元素 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`支持）。请参阅此问题和内容丰富的示例。
`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 元素关联的 popover 实例，或创建一个新的实例以防它未初始化。
`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
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`在弹出框模板添加到 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`