将 Bootstrap 弹出框(如 iOS 中的弹出框)添加到您网站上的任何元素的文档和示例。
概述
使用 popover 插件时要知道的事情:
- Popovers 依赖第三方库 Popper 进行定位。您必须在
bootstrap.js
之前包含popper.min.js
或使用包含 Popper 的bootstrap.bundle.min.js
/bootstrap.bundle.js
才能使弹出框工作! - 弹出框需要工具提示插件作为依赖项。
- 出于性能原因,弹出框是可选的,因此您必须自己初始化它们。
- 零长度的
title
和content
值永远不会显示弹出框。 - 指定
container: 'body'
以避免在更复杂的组件(如我们的输入组、按钮组等)中出现渲染问题。 - 在隐藏元素上触发弹出框将不起作用。
.disabled
或disabled
元素的弹出框必须在包装元素上触发。- 当从跨越多行的锚点触发时,弹出框将在锚点的整体宽度之间居中。在你的
<a>
上使用.text-nowrap
来避免这种行为。 - 在从 DOM 中删除其相应元素之前,必须隐藏弹出框。
- 可以通过 shadow DOM 中的元素触发弹出框。
示例:在任何地方启用弹出框
初始化页面上所有弹出框的一种方法是通过其 data-bs-toggle
属性选择它们:
var popoverTriggerList = Array.prototype.slice.call(document.querySelectorAll('[data-bs-toggle="popover"]')) var popoverList = popoverTriggerList.map(function (popoverTriggerEl) { return new bootstrap.Popover(popoverTriggerEl) })
示例:使用容器选项
当父元素上的某些样式会干扰弹出框时,您需要指定一个自定义 container
,以便弹出框的 HTML 出现在该元素中。
var popover = new bootstrap.Popover(document.querySelector('.example-popover'), { container: 'body' })
示例
<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="《因话录》" data-bs-content="唐代汉族文言笔记小说集。本书所记皆唐代事。">单击切换popover</button>
四个方向
有四个选项可用:上对齐、右对齐、下对齐和左对齐。 在 RTL 中使用 Bootstrap 时会镜像方向。
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="《三国志》"> Popover on 顶部 </button> <button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="清代长篇章回体英雄传奇小说,共68回,简称《说唐》。著者如莲居士。"> Popover on 右侧 </button> <button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="《大唐狄公案》是一部描写中国人、中国事、播扬中国古老历史和悠久文化传统、长中国人志气的中国公案小说,在中国与世界文化交流史上留下重重的一笔。"> Popover on 底部 </button> <button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="《史记》是西汉著名史学家司马迁撰写的一部纪传体史书,是中国历史上第一部纪传体通史,被列为“二十四史”之首。"> Popover on 左侧 </button>
下次点击关闭
使用焦点触发器在用户下次单击与切换元素不同的元素时关闭弹出框。
对于正确的跨浏览器和跨平台行为,您必须使用 <a>
标记,而不是 <button>
标记,并且还必须包含 tabindex
属性。
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="左传" data-bs-content="《春秋左氏传》原名《左氏春秋》,汉朝时又名《春秋左氏》、《春秋内传》,汉朝以后才多称《左传》。">下次点击时关闭</a>
var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), { trigger: 'focus' })
禁用元素
具有 disabled
属性的元素不是交互式的,这意味着用户不能悬停或单击它们来触发弹出框(或工具提示)。 作为一种解决方法,您需要从包装器 <div>
或 <span>
触发弹出框,理想情况下使用 tabindex="0"
使键盘可聚焦。
对于禁用的弹出框触发器,您可能还更喜欢 data-bs-trigger="hover focus"
以便弹出框显示为用户的即时视觉反馈,因为他们可能不希望单击禁用的元素。
<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="桃花扇"> <button class="btn btn-primary" type="button" disabled>禁用的按钮</button> </span>
用法
通过 JavaScript 启用弹出框:
var exampleEl = document.getElementById('example') var popover = new bootstrap.Popover(exampleEl, options)
要允许键盘用户激活您的弹出框,您应该只将它们添加到传统上可通过键盘聚焦和交互的 HTML
元素(例如链接或表单控件)。尽管可以通过添加 tabindex="0"
属性使任意 HTML
元素(例如 <span>
s)成为焦点,但这会为键盘用户在非交互式元素上添加可能令人讨厌和混乱的制表位,而目前大多数辅助技术都是这样做的在这种情况下不宣布弹出框的内容。此外,不要仅仅依靠悬停作为弹出框的触发器,因为这将使键盘用户无法触发它们。
虽然您可以使用 html
选项在弹出框中插入丰富的结构化 HTML
,但我们强烈建议您避免添加过多的内容。弹出框当前的工作方式是,一旦显示,它们的内容就会与带有 aria-describeby
属性的触发器元素相关联。因此,弹出框的全部内容将作为一个不间断的长流向辅助技术用户公布。
此外,虽然还可以在弹出窗口中包含交互式控件(例如表单元素或链接)(通过将这些元素添加到允许的属性和标签的允许列表中),但请注意,当前弹出窗口不管理键盘焦点顺序。当键盘用户打开一个弹出框时,焦点仍然在触发元素上,并且由于弹出框通常不会立即跟随文档结构中的触发器,因此不能保证向前移动/按下 TAB 会将键盘用户移动到弹出框本身.简而言之,简单地将交互式控件添加到弹出框可能会使键盘用户和辅助技术用户无法访问/无法使用这些控件,或者至少会导致不合逻辑的整体焦点顺序。在这些情况下,请考虑改用模态对话框。
选项
选项可以通过数据属性或 JavaScript 传递。 对于数据属性,将选项名称附加到 data-bs-
,如 data-bs-animation=""
。 通过数据属性传递选项时,请确保将选项名称的大小写类型从 驼峰命名法 更改为 短横线隔开式。 例如,不要使用 data-bs-customClass="beautifier"
,而是使用 data-bs-custom-class="beautifier"
。
sanitize
、sanitizeFn
和 allowList
选项。名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
animation |
boolean | true |
对弹出框应用 CSS 淡入淡出过渡 |
container |
string | element | false | false |
将弹出框附加到特定元素。 示例: |
content |
string | element | function | '' |
如果 如果给定了一个函数,它将被调用,并将其 |
delay |
number | object | 0 |
延迟显示和隐藏弹出框(毫秒) - 不适用于手动触发类型 如果提供了一个数字,延迟将应用于隐藏/显示 对象结构为: |
html |
boolean | false |
将 HTML 插入弹出框。 如果为 false,innerText 属性将用于将内容插入 DOM。 如果您担心 XSS 攻击,请使用文本。 |
placement |
string | function | 'right' |
如何定位弹出框 - auto | top | bottom | left | right. 当一个函数用于确定放置时,它会以弹出框 DOM 节点作为其第一个参数,触发元素 DOM 节点作为其第二个参数来调用。 |
selector |
string | false | false |
如果提供了选择器,弹出框对象将被委托给指定的目标。 在实践中,这用于启用动态 HTML 内容以添加弹出框。请参阅 这里 以及 一个信息丰富的例子. |
template |
string | '<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>' |
创建弹出框时要使用的基本 HTML。 弹出框的 弹出框的
最外层的包装元素应该有 |
title |
string | element | function | '' |
如果 如果给定了一个函数,它将被调用,并将其 |
trigger |
string | 'click' |
弹出框是如何触发的 - click | hover | focus | manual。您可以传递多个触发器; 用空格分隔它们。 manual 不能与任何其他触发器结合使用。 |
fallbackPlacements |
array | ['top', 'right', 'bottom', 'left'] |
通过提供数组中的展示位置列表(按优先顺序)来定义后备展示位置。 有关更多信息,请参阅 Popper 的 行为文档 |
boundary |
string | element | 'clippingParents' |
popover 的溢出约束边界(仅适用于 Popper 的 preventOverflow 修饰符)。 默认情况下它是 'clippingParents' 并且可以接受 HTMLElement 引用(仅通过 JavaScript)。 有关详细信息,请参阅 Popper 的 detectOverflow 文档。 |
customClass |
string | function | '' |
显示时将类添加到弹出框。 请注意,除了模板中指定的任何类之外,还将添加这些类。 要添加多个类,请用空格分隔它们: 您还可以传递一个函数,该函数应返回包含其他类名的单个字符串。 |
sanitize |
boolean | true |
启用或禁用清理。 如果激活 'template' ,'content' 和 'title' 选项将被清理。 请参阅我们的 JavaScript 文档中的 sanitizer 部分。 |
allowList |
object | 默认值 | 包含允许的属性和标签的对象 |
sanitizeFn |
null | function | null |
在这里,您可以提供自己的消毒功能。 如果您更喜欢使用专用库来执行清理,这会很有用。 |
offset |
array | string | function | [0, 8] |
弹出框相对于其目标的偏移量。 您可以使用逗号分隔值在数据属性中传递字符串,例如: 当一个函数用于确定偏移量时,调用它时会使用一个包含 popper 位置、引用和 popper rects 作为其第一个参数的对象。 触发元素 DOM 节点作为第二个参数传递。 该函数必须返回一个包含两个数字的数组: 有关详细信息,请参阅 Popper 的 偏移文档。 |
popperConfig |
null | object | function | null |
要更改 Bootstrap 的默认 Popper 配置,请参阅 Popper 的配置。 当一个函数用于创建 Popper 配置时,它会被一个包含 Bootstrap 的默认 Popper 配置的对象调用。 它可以帮助您使用默认设置并将其与您自己的配置合并。 该函数必须为 Popper 返回一个配置对象。 |
如上所述,可以通过使用数据属性来指定单个弹出框的选项。
使用带有 popperConfig
的函数
var popover = new bootstrap.Popover(element, { popperConfig: function (defaultBsPopperConfig) { // var newPopperConfig = {...} // use defaultBsPopperConfig if needed... // return newPopperConfig } })
方法
所有 API 方法都是异步的并开始一个转换。 他们在转换开始但在结束之前立即返回给调用者。 此外,过渡组件上的方法调用将被忽略。
有关更多信息,请参阅我们的 JavaScript 文档。
show
显示元素的弹出框。 在弹出框实际显示之前返回给调用者(即在 shown.bs.popover
事件发生之前)。 这被视为“手册”。 触发弹出框。 标题和内容都为零长度的弹出框永远不会显示。
myPopover.show()
hide
隐藏元素的弹出框。 在弹出框实际隐藏之前返回调用者(即在 hidden.bs.popover
事件发生之前)。 这被视为“手册”。 触发弹出框。
myPopover.hide()
toggle
切换元素的弹出框。 在弹出框实际显示或隐藏之前返回调用者(即在 shown.bs.popover
或 hidden.bs.popover
事件之前 发生)。 这被视为“手册”。 触发弹出框。
myPopover.toggle()
dispose
隐藏和销毁元素的弹出框(删除 DOM 元素上存储的数据)。 使用委托的弹出框(使用 selector
选项创建)不能在后代触发器元素上单独销毁。
myPopover.dispose()
enable
使元素的弹出框能够显示。 弹出框默认启用。
myPopover.enable()
disable
移除显示元素弹出框的能力。 只有重新启用弹出框才能显示。
myPopover.disable()
setContent
提供了一种在初始化后更改弹出框内容的方法。
myPopover.setContent({ '.popover-header': 'another title', '.popover-body': 'another content' })
setContent
方法接受一个 object
参数,其中每个属性键是弹出框模板中的有效 string
选择器,每个相关的属性值 可以是 string
| element
| function
| null
。
toggleEnabled
切换显示或隐藏元素弹出框的能力。
myPopover.toggleEnabled()
update
更新元素弹出框的位置。
myPopover.update()
getInstance
Static 方法,它允许您获取与 DOM 元素关联的弹出框实例。
var exampleTriggerEl = document.getElementById('example') var popover = bootstrap.Popover.getInstance(exampleTriggerEl) // Returns a Bootstrap popover instance
getOrCreateInstance
Static 方法,它允许您获取与 DOM 元素相关联的弹出框实例,或者在未初始化的情况下创建一个新实例。
var exampleTriggerEl = document.getElementById('example') var popover = bootstrap.Popover.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap popover instance
事件
事件类型 | 描述 |
---|---|
show.bs.popover | 此事件在调用 show 实例方法时立即触发。 |
shown.bs.popover | 当弹出框对用户可见时触发此事件(将等待 CSS 转换完成)。 |
hide.bs.popover | 当调用 hide 实例方法时,会立即触发此事件。 |
hidden.bs.popover | 当弹出窗口完成对用户隐藏时触发此事件(将等待 CSS 转换完成)。 |
inserted.bs.popover | 当弹出框模板添加到 DOM 时,此事件在 show.bs.popover 事件之后触发。 |
var myPopoverTrigger = document.getElementById('myPopover') myPopoverTrigger.addEventListener('hidden.bs.popover', function () { // do something... })