Popovers

概述

🌐 Overview

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

🌐 Things to know when using the popover plugin:

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

继续阅读一些示例，了解弹出窗口如何工作。

🌐 Keep reading to see how popovers work with some examples.

示例

🌐 Examples

启用弹出窗口

🌐 Enable popovers

如上所述，必须先初始化弹出框才能使用它们。初始化页面上所有弹出框的一种方法是通过它们的 data-bs-toggle 属性来选择它们，如下所示：

🌐 As mentioned above, you must initialize popovers before they can be used. One way to initialize all popovers on a page would be to select them by their data-bs-toggle attribute, like so:

const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]')
const popoverList = [...popoverTriggerList].map(popoverTriggerEl => new bootstrap.Popover(popoverTriggerEl))

在线演示

🌐 Live demo

我们使用类似上面片段的 JavaScript 来渲染以下实时弹出框。标题通过 data-bs-title 设置，正文内容通过 data-bs-content 设置。

🌐 We use JavaScript similar to the snippet above to render the following live popover. Titles are set via data-bs-title and body content is set via data-bs-content.

<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" data-bs-title="弹出框标题" data-bs-content="And here’s some amazing content. It’s very engaging. Right?">Click to toggle popover</button>

四个方向

🌐 Four directions

有四个可用选项：上、右、下和左。在使用 RTL 的 Bootstrap 时，方向会被镜像。设置 data-bs-placement 可以更改方向。

🌐 Four options are available: top, right, bottom, and left. Directions are mirrored when using Bootstrap in RTL. Set data-bs-placement to change the direction.

<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

🌐 Custom container

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

🌐 When you have some styles on a parent element that interfere with a popover, you’ll want to specify a custom container so that the popover’s HTML appears within that element instead. This is common in responsive tables, input groups, and the like.

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

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

🌐 Another situation where you’ll want to set an explicit custom container are popovers inside a modal dialog, to make sure that the popover itself is appended to the modal. This is particularly important for popovers that contain interactive elements – modal dialogs will trap focus, so unless the popover is a child element of the modal, users won’t be able to focus or activate these interactive elements.

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

定制弹出窗口

🌐 Custom popovers

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

🌐 You can customize the appearance of popovers using CSS variables. We set a custom class with data-bs-custom-class="custom-popover" to scope our custom appearance and use it to override some of the local CSS variables.

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

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

下次点击时关闭

🌐 Dismiss on next click

使用 focus 触发器在用户下一次点击切换元素以外的元素时关闭弹出框。

🌐 Use the focus trigger to dismiss popovers on the user’s next click of an element other than the toggle element.

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

带有 disabled 属性的元素不可交互，这意味着用户无法悬停或点击它们来触发弹出框（或工具提示）。作为一种解决方法，你可以从一个封装器 <div> 或 <span> 触发弹出框，最好使用 tabindex="0" 使其可通过键盘聚焦。

🌐 Elements with the disabled attribute aren’t interactive, meaning users cannot hover or click them to trigger a popover (or tooltip). As a workaround, you’ll want to trigger the popover from a wrapper <div> or <span>, ideally made keyboard-focusable using tabindex="0".

对于已禁用的弹出触发器，你可能也更喜欢使用 data-bs-trigger="hover focus"，这样弹出框会作为即时的视觉反馈出现在用户面前，因为他们可能不会期望点击一个已禁用的元素。

🌐 For disabled popover triggers, you may also prefer data-bs-trigger="hover focus" so that the popover appears as immediate visual feedback to your users as they may not expect to click on a disabled element.

<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

变量

🌐 Variables

作为 Bootstrap 不断发展的 CSS 变量方法的一部分，弹出框现在在 .popover 上使用本地 CSS 变量，以增强实时自定义。CSS 变量的值通过 Sass 设置，因此仍然支持 Sass 自定义。

🌐 As part of Bootstrap’s evolving CSS variables approach, popovers now use local CSS variables on .popover for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

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

🌐 Sass variables

$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;

用法

🌐 Usage

通过 JavaScript 启用弹出窗口：

🌐 Enable popovers via JavaScript:

const exampleEl = document.getElementById('example')
const popover = new bootstrap.Popover(exampleEl, options)

选项

🌐 Options

As options can be passed via data attributes or JavaScript, you can append an option name to data-bs-, as in data-bs-animation="{value}". Make sure to change the case type of the option name from “camelCase” to “kebab-case” when passing the options via data attributes. For example, use data-bs-custom-class="beautifier" instead of data-bs-customClass="beautifier".

As of Bootstrap 5.2.0, all components support an experimental reserved data attribute data-bs-config that can house simple component configuration as a JSON string. When an element has data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456 and the separate data attributes will override values given on data-bs-config. In addition, existing data attributes are able to house JSON values like data-bs-delay='{"show":0,"hide":150}'.

The final configuration object is the merged result of data-bs-config, data-bs-, and js object where the latest given key-value overrides the others.

使用带有 popperConfig 的函数

🌐 Using function with popperConfig

const popover = new bootstrap.Popover(element, {
  popperConfig(defaultBsPopperConfig) {
    // const newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

方法

🌐 Methods

// 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'
})

事件

🌐 Events

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