Popovers

概述

¥Overview

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

¥Things to know when using the popover plugin:

• Popovers 依赖第三方库 Popper 进行定位。你必须在 bootstrap.js 之前包含 popper.min.js，或使用包含 Popper 的 bootstrap.bundle.min.js。

  ¥Popovers rely on the third party library Popper for positioning. You must include popper.min.js before bootstrap.js, or use one bootstrap.bundle.min.js which contains Popper.

• 弹出窗口需要 弹出窗口插件 作为依赖。

  ¥Popovers require the popover plugin as a dependency.

• 出于性能原因，弹出窗口是可选的，因此你必须自己初始化它们。

  ¥Popovers are opt-in for performance reasons, so you must initialize them yourself.

• 零长度 title 和 content 值永远不会显示弹出窗口。

  ¥Zero-length title and content values will never show a popover.

• 指定 container: 'body' 以避免更复杂的组件（例如我们的输入组、按钮组等）中出现渲染问题。

  ¥Specify container: 'body' to avoid rendering problems in more complex components (like our input groups, button groups, etc).

• 在隐藏元素上触发弹出窗口将不起作用。

  ¥Triggering popovers on hidden elements will not work.

• .disabled 或 disabled 元素的弹出窗口必须在封装元素上触发。

  ¥Popovers for .disabled or disabled elements must be triggered on a wrapper element.

• 当从跨多行的锚点触发时，弹出窗口将在锚点的整体宽度之间居中。在 <a> 上使用 .text-nowrap 可以避免这种行为。

  ¥When triggered from anchors that wrap across multiple lines, popovers will be centered between the anchors’ overall width. Use .text-nowrap on your <a>s to avoid this behavior.

• 在从 DOM 中删除相应的元素之前，必须隐藏弹出窗口。

  ¥Popovers must be hidden before their corresponding elements have been removed from the DOM.

• 弹出窗口可以通过影子 DOM 内的元素来触发。

  ¥Popovers can be triggered thanks to an element inside a shadow 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="Popover 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...
})