Skip to main content Skip to docs navigation
View on GitHub

Popovers弹出提示框

Documentation and examples for adding Bootstrap popovers, like those found in iOS, to any element on your site.向站点上的任何元素添加Bootstrap弹出窗口（如iOS中的弹出窗口）的文档和示例。

On this page本页内容

Overview概述

Things to know when using the popover plugin:使用popover插件时需要了解的事项：

  • Popovers rely on the 3rd party library Popper for positioning. 弹出提示框依靠第三方库Popper进行定位。You must include popper.min.js before bootstrap.js or use bootstrap.bundle.min.js / bootstrap.bundle.js which contains Popper in order for popovers to work!你必须在bootstrap.js前面包含popper.min.js，或者使用bootstrap.bundle.min.js/bootstrap.bundle.js，它们已经包含了Proper，从而使弹出提示框正常起作用。
  • Popovers require the tooltip plugin as a dependency.弹出提示框需要工具提示插件作为依赖项。
  • Popovers are opt-in for performance reasons, so you must initialize them yourself.由于性能原因，弹出框是可选的，所以您必须自己初始化它们。
  • Zero-length title and content values will never show a popover.长度为零的title值和content值永远不会显示弹出框。
  • Specify container: 'body' to avoid rendering problems in more complex components (like our input groups, button groups, etc).指定container: 'body'以避免在更复杂的组件（如输入组、按钮组等）中出现渲染问题。
  • Triggering popovers on hidden elements will not work.在隐藏元素上触发弹出窗口将不起作用。
  • Popovers for .disabled or disabled elements must be triggered on a wrapper element.必须在包装器元素上触发.disabled或disabled元素的弹出框。
  • 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.在您的<a>上使用.text-nowrap；这是为了避免这种行为。
  • 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.由于影子DOM中的元素，所以可以触发弹出框。
By default, this component uses the built-in content sanitizer, which strips out any HTML elements that are not explicitly allowed. 默认情况下，此组件使用内置的内容消毒器，该消毒器会去除任何不明确允许的HTML元素。See the sanitizer section in our JavaScript documentation for more details.有关更多详细信息，请参阅JavaScript文档中的“消毒剂”部分。
The animation effect of this component is dependent on the prefers-reduced-motion media query. 此组件的动画效果取决于prefers-reduced-motion媒体查询。See the reduced motion section of our accessibility documentation.请参阅我们的易访问性文档中的简化运动部分。

Keep reading to see how popovers work with some examples.继续阅读一些例子，看看流行音乐是如何工作的。

Example: Enable popovers everywhere示例：在任何地方启用弹出窗口

One way to initialize all popovers on a page would be to select them by their data-bs-toggle attribute:初始化页面上所有弹出框的一种方法是通过其data-bs-toggle属性选择它们：

var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
return new bootstrap.Popover(popoverTriggerEl)
})

Example: Using the container option示例：使用container选项

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.当父元素上的某些样式干扰了popover时，您需要指定一个container容器，以便popover的HTML显示在该元素中。

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

Example例子

<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>

Four directions四个方向

Four options are available: top, right, bottom, and left aligned. 有四个选项可用：上对齐、右对齐、下对齐和左对齐。Directions are mirrored when using Bootstrap in RTL.在RTL中使用Bootstrap时会镜像方向。

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

Dismiss on next click下一次单击时撤除

Use the focus trigger to dismiss popovers on the user’s next click of a different element than the toggle element.用户下一次单击不同于toggle元素的元素时，使用focus触发器关闭弹出框。

Specific markup required for dismiss-on-next-click下一次单击时解除所需的特定标记

For proper cross-browser and cross-platform behavior, you must use the <a> tag, not the <button> tag, and you also must include a tabindex attribute.

Dismissible popover 
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
trigger: 'focus'
})

Disabled elements禁用元素

Elements with the disabled attribute aren’t interactive, meaning users cannot hover or click them to trigger a popover (or tooltip). 具有disabled属性的元素是非交互式的，这意味着用户不能悬停或单击它们来触发popover（或工具提示）。As a workaround, you’ll want to trigger the popover from a wrapper <div> or <span>, ideally made keyboard-focusable using tabindex="0".作为一种解决方法，您需要从包装器<div>或<span>触发弹出窗口，理想情况下使用tabindex="0"使键盘可聚焦。

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.对于禁用的popover触发器，您也可以选择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>

Sass

Variables变量

$popover-font-size:                 $font-size-sm;
$popover-bg:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              rgba($black, .2);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;
$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;
$popover-arrow-color:               $popover-bg;
$popover-arrow-outer-color:         fade-in($popover-border-color, .05);

Usage用法

Enable popovers via JavaScript:通过JavaScript启用弹出窗口：

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

Making popovers work for keyboard and assistive technology users为键盘和辅助技术用户制作Popover

To allow keyboard users to activate your popovers, you should only add them to HTML elements that are traditionally keyboard-focusable and interactive (such as links or form controls). 要允许键盘用户激活您的弹出框，您应该只将它们添加到传统上以键盘为焦点且交互的HTML元素中（例如链接或表单控件）。Although arbitrary HTML elements (such as <span>s) can be made focusable by adding the tabindex="0" attribute, this will add potentially annoying and confusing tab stops on non-interactive elements for keyboard users, and most assistive technologies currently do not announce the popover’s content in this situation. 尽管任意HTML元素（譬如<span>）都可以添加tabindex="0"属性，但是这将为键盘用户在非交互元素上添加潜在的恼人和混乱的制表位，并且大多数辅助技术目前不会在这种情况下公布popover的内容。Additionally, do not rely solely on hover as the trigger for your popovers, as this will make them impossible to trigger for keyboard users.此外，不要仅仅依靠hover作为弹出框的触发器，因为这将使键盘用户无法触发弹出框。

While you can insert rich, structured HTML in popovers with the html option, we strongly recommend that you avoid adding an excessive amount of content. 虽然您可以使用html选项在弹出窗口中插入丰富的结构化HTML，但我们强烈建议您避免添加过多的内容。The way popovers currently work is that, once displayed, their content is tied to the trigger element with the aria-describedby attribute. 弹出窗口当前的工作方式是，一旦显示，它们的内容将绑定到具有aria-describedby属性的触发器元素。As a result, the entirety of the popover’s content will be announced to assistive technology users as one long, uninterrupted stream.因此，popover的全部内容将作为一条长而不间断的流向辅助技术用户发布。

Additionally, while it is possible to also include interactive controls (such as form elements or links) in your popover (by adding these elements to the allowList of allowed attributes and tags), be aware that currently the popover does not manage keyboard focus order. 此外，虽然也可以在popover中包含交互控件（例如表单元素或链接）（通过将这些元素添加到允许的属性和标记的allowList中），但请注意，popover当前不管理键盘焦点顺序。When a keyboard user opens a popover, focus remains on the triggering element, and as the popover usually does not immediately follow the trigger in the document’s structure, there is no guarantee that moving forward/pressing TAB will move a keyboard user into the popover itself. 当键盘用户打开popover时，焦点仍在触发元素上，并且由于popover通常不会立即跟随文档结构中的触发器，因此无法保证向前移动/按TAB键会将键盘用户移动到popover本身中。In short, simply adding interactive controls to a popover is likely to make these controls unreachable/unusable for keyboard users and users of assistive technologies, or at the very least make for an illogical overall focus order. 简言之，简单地将交互式控件添加到popover可能会使键盘用户和辅助技术用户无法访问/无法使用这些控件，或者至少会导致整体焦点顺序不合逻辑。In these cases, consider using a modal dialog instead.在这些情况下，考虑使用模态对话框来代替。

Options选项

Options can be passed via data attributes or JavaScript. 选项可以通过数据属性或JavaScript传递。For data attributes, append the option name to data-bs-, as in data-bs-animation="". 对于数据属性，将选项名称附加到data-bs-，如data-bs-animation=""。Make sure to change the case type of the option name from camelCase to kebab-case when passing the options via data attributes. 通过数据属性传递选项时，确保将选项名称的大小写类型从camelCase更改为kebab case。For example, instead of using data-bs-customClass="beautifier", use data-bs-custom-class="beautifier".例如，不是使用data-bs-customClass="beautifier"，而是使用data-bs-custom-class="beautifier"。

Note that for security reasons the sanitize, sanitizeFn, and allowList options cannot be supplied using data attributes.请注意，出于安全原因，不能使用数据属性提供sanitize、sanitizeFn和allowList选项。
Name名称 Type类型 Default默认值 Description描述
animation boolean true Apply a CSS fade transition to the popover对popover应用CSS淡入淡出过渡
container string | element | false false

Appends the popover to a specific element. 将popover附加到特定元素。Example: container: 'body'. 示例：container: 'body'。This option is particularly useful in that it allows you to position the popover in the flow of the document near the triggering element - which will prevent the popover from floating away from the triggering element during a window resize.此选项特别有用，因为它允许您将弹出窗口放置在文档流中靠近触发元素的位置，这将防止弹出窗口在调整窗口大小时从触发元素浮动。
content string | element | function ''

Default content value if data-bs-content attribute isn't present.如果data-bs-content属性不存在，则为默认内容值。

If a function is given, it will be called with its this reference set to the element that the popover is attached to.如果给定了一个函数，则将调用它并令其this引用设置为弹出窗口附加到的元素。
delay number | object 0

Delay showing and hiding the popover (ms) - does not apply to manual trigger type延迟显示和隐藏popover(ms)-不适用于手动触发器类型

If a number is supplied, delay is applied to both hide/show如果提供了数字，则延迟将应用于隐藏/显示

Object structure is: 对象结构为：delay: { "show": 500, "hide": 100 }
html boolean false Insert HTML into the popover. 在弹出窗口中插入HTML。If false, innerText property will be used to insert content into the DOM. 如果为false，innerText属性将用于将内容插入DOM。Use text if you're worried about XSS attacks.如果您担心XSS攻击，请使用文本。
placement string | function 'right'

How to position the popover - auto | top | bottom | left | right.如何定位popover：auto | top | bottom | left | right。
When auto is specified, it will dynamically reorient the popover.当指定auto时，它将动态重新定向弹出窗口。

When a function is used to determine the placement, it is called with the popover DOM node as its first argument and the triggering element DOM node as its second. 当使用函数确定位置时，调用该函数时，popover DOM节点作为其第一个参数，触发元素DOM节点作为其第二个参数。The this context is set to the popover instance.this上下文设置为popover实例。
selector string | false false If a selector is provided, popover objects will be delegated to the specified targets. 如果提供了选择器，则popover对象将委托给指定的目标。In practice, this is used to enable dynamic HTML content to have popovers added. 实际上，这是用来允许动态HTML内容添加弹出框的。See this and an informative example.请参阅此处和一个信息性示例。
template string '<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

Base HTML to use when creating the popover.创建popover时要使用的基本HTML。

The popover's title will be injected into the .popover-header.弹出窗口的title将被注入到.popover-header中。

The popover's content will be injected into the .popover-body.弹出窗口的content将被注入.popover-body。

.popover-arrow will become the popover's arrow.将成为教皇的箭。

The outermost wrapper element should have the .popover class.最外层的包装器元素应该具有.popover类。
title string | element | function ''

Default title value if title attribute isn't present.如果title属性不存在，则为默认标题值。

If a function is given, it will be called with its this reference set to the element that the popover is attached to.如果给定了一个函数，将调用该函数，并将其this引用设置为popover所连接的元素。
trigger string 'click' How popover is triggered - click | hover | focus | manual. 如何触发弹出窗口-click | hover | focus | manual。You may pass multiple triggers; separate them with a space. 您可以传递多个触发器；用空格隔开它们。manual cannot be combined with any other trigger.不能与任何其他触发器组合。
fallbackPlacements array ['top', 'right', 'bottom', 'left'] Define fallback placements by providing a list of placements in array (in order of preference). 通过在数组中提供放置列表（按优先顺序）来定义后备放置。For more information refer to Popper's behavior docs有关更多信息，请参阅Popper的行为文档
boundary string | element 'clippingParents' Overflow constraint boundary of the popover (applies only to Popper's preventOverflow modifier). popover的溢出约束边界（仅适用于Popper的preventOverflow修饰符）。By default it's 'clippingParents' and can accept an HTMLElement reference (via JavaScript only). 默认情况下，它是'clippingParents'，可以接受HTMLElement引用（仅通过JavaScript）。For more information refer to Popper's detectOverflow docs.有关更多信息，请参阅Popper的detectOverflow文档。
customClass string | function ''

Add classes to the popover when it is shown. 在弹出窗口显示时向其添加类。Note that these classes will be added in addition to any classes specified in the template. 请注意，这些类将添加到模板中指定的任何类之外。To add multiple classes, separate them with spaces: 'class-1 class-2'.要添加多个类，请使用空格分隔它们：'class-1 class-2'。

You can also pass a function that should return a single string containing additional class names.您还可以传递一个函数，该函数应返回包含其他类名的单个字符串。
sanitize boolean true Enable or disable the sanitization. 启用或禁用净化。If activated 'template', 'content' and 'title' options will be sanitized. 如果激活了'template'，'content'和'title'选项将被清除。See the sanitizer section in our JavaScript documentation.请参阅JavaScript文档中的sanitizer部分。
allowList object Default value Object which contains allowed attributes and tags对象，该对象包含允许的属性和标记
sanitizeFn null | function null Here you can supply your own sanitize function. 在这里，您可以提供自己的消毒功能。This can be useful if you prefer to use a dedicated library to perform sanitization.如果您喜欢使用专用库来执行消毒，这可能非常有用。
offset array | string | function [0, 8]

Offset of the popover relative to its target. popover相对于其目标的偏移量。You can pass a string in data attributes with comma separated values like: 可以使用逗号分隔的值在数据属性中传递字符串，如：data-bs-offset="10,20"

When a function is used to determine the offset, it is called with an object containing the popper placement, the reference, and popper rects as its first argument. 当使用函数确定偏移量时，将使用包含popper placement、reference和popper rects的对象作为其第一个参数来调用该函数。The triggering element DOM node is passed as the second argument. 触发元素DOM节点作为第二个参数传递。The function must return an array with two numbers: 函数必须返回包含两个数字的数组：[skidding, distance].

For more information refer to Popper's offset docs.有关更多信息，请参阅Popper的偏移文档。
popperConfig null | object | function null

To change Bootstrap's default Popper config, see Popper's configuration.要更改Bootstrap的默认Popper配置，请参阅Popper的配置。

When a function is used to create the Popper configuration, it's called with an object that contains the Bootstrap's default Popper configuration. 当一个函数用于创建Popper配置时，将使用包含Bootstrap的默认Popper配置的对象调用它。It helps you use and merge the default with your own configuration. 它帮助您使用默认设置并将其与您自己的配置合并。The function must return a configuration object for Popper.函数必须返回Popper的配置对象。

Data attributes for individual popovers单个Popover的数据属性

Options for individual popovers can alternatively be specified through the use of data attributes, as explained above.如上文所述，也可以通过使用数据属性来指定各个弹出框的选项。

Using function with 使用函数配合popperConfig

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

Methods方法

Asynchronous methods and transitions异步方法和转换

All API methods are asynchronous and start a transition. 所有API方法都是异步的，并开始转换。They return to the caller as soon as the transition is started but before it ends. 转换一开始，它们就返回到调用者，但在转换结束之前。In addition, a method call on a transitioning component will be ignored.此外，转换组件上的方法调用将被忽略。

See our JavaScript documentation for more information有关更多信息，请参阅JavaScript文档.

show

Reveals an element’s popover. 显示元素的popover。Returns to the caller before the popover has actually been shown在实际显示popover之前返回给调用者 (i.e. before the shown.bs.popover event occurs). （即，在shown.bs.popover事件发生之前）。This is considered a “manual” triggering of the popover. 这被认为是popover的“手动”触发。Popovers whose title and content are both zero-length are never displayed.标题和内容均为零长度的弹出窗口永远不会显示。

myPopover.show()

hide

Hides an element’s popover. 隐藏元素的popover。Returns to the caller before the popover has actually been hidden在popover实际隐藏之前返回给调用方 (i.e. before the hidden.bs.popover event occurs). （即，在hidden.bs.popover事件发生之前）。This is considered a “manual” triggering of the popover.这被认为是弹出窗口的“手动”触发。

myPopover.hide()

toggle

Toggles an element’s popover. 切换元素的弹出窗口。Returns to the caller before the popover has actually been shown or hidden在弹出窗口实际显示或隐藏之前返回给调用者 (i.e. before the shown.bs.popover or hidden.bs.popover event occurs). （即在shown.bs.popover或hhidden.bs.popover事件发生之前）。This is considered a “manual” triggering of the popover.这被认为是弹出窗口的“手动”触发。

myPopover.toggle()

dispose

Hides and destroys an element’s popover (Removes stored data on the DOM element). 隐藏和销毁元素的popover（删除DOM元素上存储的数据）。Popovers that use delegation (which are created using the selector option) cannot be individually destroyed on descendant trigger elements.使用委托的弹出窗口（使用selector选项创建）不能在后代触发器元素上单独销毁。

myPopover.dispose()

enable

Gives an element’s popover the ability to be shown. 赋予元素的弹出窗口显示的能力。Popovers are enabled by default.默认情况下启用弹出窗口。

myPopover.enable()

disable

Removes the ability for an element’s popover to be shown. 删除显示元素弹出窗口的功能。The popover will only be able to be shown if it is re-enabled.仅当重新启用时，才能显示弹出窗口。

myPopover.disable()

toggleEnabled

Toggles the ability for an element’s popover to be shown or hidden.切换显示或隐藏元素弹出窗口的功能。

myPopover.toggleEnabled()

update

Updates the position of an element’s popover.更新元素弹出窗口的位置。

myPopover.update()

getInstance

Static method which allows you to get the popover instance associated with a DOM element静态方法，允许您获取与DOM元素关联的popover实例

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

getOrCreateInstance

Static method which allows you to get the popover instance associated with a DOM element, or create a new one in case it wasn’t initialised静态方法，允许您获取与DOM元素关联的popover实例，或者在未初始化的情况下创建一个新实例

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

Events事件

Event type事件类型 Description描述
show.bs.popover This event fires immediately when the show instance method is called.调用show实例方法时，此事件立即激发。
shown.bs.popover This event is fired when the popover has been made visible to the user (will wait for CSS transitions to complete).此事件在popover对用户可见时触发（将等待CSS转换完成）。
hide.bs.popover This event is fired immediately when the hide instance method has been called.调用hide实例方法后，将立即触发此事件。
hidden.bs.popover This event is fired when the popover has finished being hidden from the user (will wait for CSS transitions to complete).当popover对用户完成隐藏时（将等待CSS转换完成），将触发此事件。
inserted.bs.popover This event is fired after the show.bs.popover event when the popover template has been added to the DOM.将popover模板添加到DOM后，在show.bs.popover事件之后激发此事件。 
var myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
// do something...
})