弹出式窗口(Popovers)

用于将Bootstrap弹出式窗口(如iOS中发现的)添加到网站上任何元素的文档和示例。

概览

使用popover插件时要了解的事项

  • Popovers rely on the 3rd party library Popper.js for positioning. You must include popper.min.js before bootstrap.js or use bootstrap.bundle.min.js / bootstrap.bundle.js which contains Popper.js in order for popovers to work!
  • Popovers require the tooltip plugin as a dependency.
  • If you’re building our JavaScript from source, it requires util.js.
  • 出于性能方面的考虑,选择加入弹出式窗口,因此您必须自己对其进行初始化
  • 零长度的“标题”和“内容”值将永远不会显示弹出框。
  • 指定`container:’body’以避免在更复杂的组件(例如我们的输入组,按钮组等)中出现渲染问题。
  • 在隐藏元素上触发弹出窗口将不起作用。
  • 必须在包装元素上触发“ .disabled”或“ disabled”元素的弹出窗口。
  • 从跨越多行的锚点触发时,弹出窗口将在锚点的整体宽度之间居中。 在您的上使用.text-nowrap可以避免这种情况。
  • 必须先隐藏弹出窗口,然后才能从DOM中删除其相应元素。
  • 由于影子DOM中的元素,可以触发弹出窗口。

The animation effect of this component is dependent on the prefers-reduced-motion media query. See the reduced motion section of our accessibility documentation.

继续阅读以了解一些示例如何处理弹出窗口。

示例:在各处启用弹出窗口

初始化页面上所有弹出窗口的一种方法是通过其data-toggle属性选择它们:

$(function () {
  $('[data-toggle="popover"]').popover()
})

示例:使用container选项

当父元素上的某些样式会干扰弹出框时,您需要指定一个自定义的“容器”,以便弹出框的HTML出现在该元素内。

$(function () {
  $('.example-popover').popover({
    container: 'body'
  })
})

例子

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

四个方向

共有四个选项:顶部,右侧,底部和左侧对齐。

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover on top
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover on right
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus
sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover on bottom
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
  Popover on left
</button>

下次点击时关闭

使用focus触发器可以消除用户在下次单击与切换元素不同的元素上的弹出窗口。

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

为了实现正确的跨浏览器和跨平台行为,您必须使用<a>标签,not<button>标签,并且还必须包含tabindex 属性。

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

禁用元素

具有“ disabled”属性的元素不是交互式的,这意味着用户无法悬停或单击它们来触发弹出窗口(或工具提示)。 解决方法是,您要从包装器<div>或触发弹出窗口,并覆盖禁用元素上的指针事件。

对于禁用的弹出式触发器,您可能还希望使用“ data-trigger =“ hover”`,这样弹出式窗口会立即显示给您的用户视觉反馈,因为他们可能不希望单击禁用元素。

<span class="d-inline-block" data-toggle="popover" data-content="Disabled popover">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

用法

通过JavaScript启用弹出窗口:

$('#example').popover(options)

使弹出窗口对键盘和辅助技术用户有效

要允许键盘用户激活您的弹出框,您应该只将其添加到传统上可键盘聚焦和交互的HTML元素中(例如链接或表单控件)。尽管通过添加tabindex =“ 0”属性可以使任意HTML元素(例如`s)成为可聚焦的,但这将为键盘用户和大多数用户在非交互式元素上添加潜在的令人讨厌的和令人困惑的制表位。在这种情况下,辅助技术目前无法宣布弹出窗口的内容。另外,不要仅仅依靠“ hover”作为弹出窗口的触发,因为这将使它们无法为键盘用户触发。

虽然您可以使用html选项在弹出窗口中插入丰富的结构化HTML,但我们强烈建议您避免添加过多的内容。弹出窗口当前的工作方式是,一旦显示,其内容将通过“ aria- describeby”属性与触发元素绑定。结果,弹出窗口的全部内容将作为一条长而连续的流向辅助技术用户宣布。

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

选项(Options)

可以通过数据属性或JavaScript传递选项。 对于数据属性,将选项名称附加到data-中,如`data-animation =“”中所示。

Note that for security reasons the sanitize, sanitizeFn and whiteList options cannot be supplied using data attributes.

Name Type Default Description
animation boolean true Apply a CSS fade transition to the popover
container string | element | false false

Appends the popover to a specific element. Example: 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-content attribute isn't present.

If a function is given, it will be called with its this reference set to the element that the popover is attached to.

delay number | object 0

Delay showing and hiding the popover (ms) - does not apply to manual trigger type

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. If false, jQuery's text method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.
placement string | function 'right'

How to position the popover - auto | top | bottom | left | right.
When auto is specified, it will dynamically reorient the popover.

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. The this context is set to the popover instance.

selector string | false false If a selector is provided, popover objects will be delegated to the specified targets. In practice, this is used to enable dynamic HTML content to have popovers added. See this and an informative example.
template string '<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

Base HTML to use when creating the popover.

The popover's title will be injected into the .popover-header.

The popover's content will be injected into the .popover-body.

.arrow will become the popover's arrow.

The outermost wrapper element should have the .popover class.

title string | element | function ''

Default title value if title attribute isn't present.

If a function is given, it will be called with its this reference set to the element that the popover is attached to.

trigger string 'click' How popover is triggered - click | hover | focus | manual. You may pass multiple triggers; separate them with a space. manual cannot be combined with any other trigger.
offset number | string 0 Offset of the popover relative to its target. For more information refer to Popper.js's offset docs.
fallbackPlacement string | array 'flip' Allow to specify which position Popper will use on fallback. For more information refer to Popper.js's behavior docs
boundary string | element 'scrollParent' Overflow constraint boundary of the popover. Accepts the values of 'viewport', 'window', 'scrollParent', or an HTMLElement reference (JavaScript only). For more information refer to Popper.js's preventOverflow docs.
sanitize boolean true Enable or disable the sanitization. If activated 'template', 'content' and 'title' options will be sanitized.
whiteList 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.
popperConfig null | object null To change Bootstrap's default Popper.js config, see Popper.js's configuration

单个弹出窗口的数据属性

如上所述,可以单独使用数据属性指定各个弹出窗口的选项。

方法(Methods)

Asynchronous methods and transitions

All API methods are asynchronous and start a transition. 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.

$().popover(options)

初始化元素集合的弹出窗口。

.popover('show')

显示元素的弹出框。 在实际显示弹出窗口之前返回调用者(即在shown.bs.popover事件发生之前)。 这被认为是弹出窗口的“手动”触发。 标题和内容均为零长度的弹出窗口永远不会显示。

$('#element').popover('show')

.popover('hide')

隐藏元素的弹出框。 在实际隐藏弹出窗口之前返回调用者(即在发生“ hidden.bs.popover”事件之前)。 这被认为是弹出窗口的“手动”触发。

$('#element').popover('hide')

.popover('toggle')

切换元素的弹出框。 在实际显示或隐藏弹出窗口之前返回调用者(即在“ shown.bs.popover”或“ hidden.bs.popover”事件发生之前)。 这被认为是弹出窗口的“手动”触发。

$('#element').popover('toggle')

.popover('dispose')

隐藏和销毁元素的弹出框。 使用委派的弹出窗口the selector option)不能在后代触发器元素上单独销毁。

$('#element').popover('dispose')

.popover('enable')

使元素的弹出框具有显示能力。 默认情况下启用Popovers。

$('#element').popover('enable')

.popover('disable')

删除显示元素弹出框的功能。 仅当重新启用弹出窗口时,才能显示该弹出窗口。

$('#element').popover('disable')

.popover('toggleEnabled')

切换显示或隐藏元素的弹出框的功能。

$('#element').popover('toggleEnabled')

.popover('update')

更新元素弹出框的位置。

$('#element').popover('update')

事件(Events)

Event Type Description
show.bs.popover This event fires immediately when the show instance method is called.
shown.bs.popover This event is fired when the popover has been made visible to the user (will wait for CSS transitions to complete).
hide.bs.popover This event is fired immediately when the hide instance method has been called.
hidden.bs.popover This event is fired when the popover has finished being hidden from the user (will wait for CSS transitions to complete).
inserted.bs.popover This event is fired after the show.bs.popover event when the popover template has been added to the DOM.
$('#myPopover').on('hidden.bs.popover', function () {
  // do something...
})