指示备注(Popover)
Popover特性提供了类似工具提示的行为,可以通过 <b-popover>
组件
或v-b-popover
指令轻松地应用到任何交互式元素。
概述
使用popover组件时需要知道的事项:
-
Popover依赖于第三方库Popper.js进行定位。
- 弹出窗口需要BootstrapVue的自定义s CSS/CSS才能正常工作,也需要变量
-
将
container
指定为null
(默认值,追加到<body>
),以避免在更复杂的组件(如输入组、按钮组等)中出现呈现问题。
可以使用container
指定要将呈现的popover附加到的其他元素。
- 在隐藏元素上触发弹出按钮将不起作用。
-
必须在包装器元素上触发
禁用
元素的弹出窗口。
-
当从跨越多行的超链接触发时,弹出窗口将居中。在
<a>
s,
<b-link>
s和
<router-link>
s上使用空格:nowrap
;以避免此行为。
在装入<b-popover>
之前,目标元素必须存在于文档中。如果在装载期间找不到目标元素,则popover将永远不会打开。
始终将<b-popover>
组件放在DOM中低于目标元素的位置。
定位
有12个选项可用于定位: top
,
topleft
,
topright
,
right
,
righttop
,
rightbottom
,
bottom
,
bottomleft
,
bottomright
,
left
,
lefttop
,和
leftbottom
。定位是相对于触发器元素的。
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia
quam venenatis vestibulum.
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia
quam venenatis vestibulum.
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia
quam venenatis vestibulum.
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia
quam venenatis vestibulum.
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia
quam venenatis vestibulum.
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia
quam venenatis vestibulum.
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia
quam venenatis vestibulum.
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia
quam venenatis vestibulum.
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia
quam venenatis vestibulum.
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia
quam venenatis vestibulum.
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia
quam venenatis vestibulum.
Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia
quam venenatis vestibulum.
触发器
弹出窗口可以通过click
,
hover
和
focus
的任意组合触发(打开/关闭)。
默认触发器是click
。或者可以指定手动
触发器,
其中只能以编程方式打开或关闭弹出窗口。
如果弹出窗口有多个触发器,则必须清除所有触发器,然后才能关闭弹出窗口。
如果弹出窗口有触发焦点单击
,并且它是由焦点
打开的,
然后用户单击触发元素,他们必须再次单击它并移动焦点以关闭弹出窗口。
为了在仅使用焦点
触发器时获得正确的跨浏览器和跨平台行为,
必须使用呈现<a>
标记的元素,
而不是<button>
标记,并且还必须包含tabindex="0"
属性。
下面将生成一个看起来像按钮的<a>
:
下次单击时关闭(自行关闭)
使用focus
触发器本身在用户下一次单击时关闭弹出窗口。
focus
还使popover在focus
和click
上都被激活
(因为click使元素在大多数浏览器上接收focus,假设它在页面的tab序列中)。
但是,您可以将触发器指定为click blur
,这将使单击激活弹出窗口,单击元素或将焦点丢失到另一个元素或文档的一部分将关闭弹出窗口。
特殊模糊
触发器必须与单击触发器结合使用。
<b-popover>
组件基本用法
Placement
Content via properties or slots
通过属性的组件选项
属性 |
默认值 |
描述 |
支持的值 |
target |
null |
要触发弹出窗口的元素字符串ID或对元素或组件的引用。Required |
任何有效的文档内唯一元素ID或文档内元素/组件参考 |
title |
null |
弹出式标题(仅文本,无HTML)。如果需要HTML或reactivity,请使用名为slot的标题
|
纯文本 |
content |
null |
Popover内容(仅文本,不使用HTML)。如果需要HTML或reactivity,请使用默认槽 |
纯文本 |
placement |
'right' |
相对于触发器元素定位弹出窗口。 |
auto , top , bottom , left , right , topleft , topright , bottomleft , bottomright , lefttop , leftbottom , righttop , rightbottom |
fallback-placement |
'flip' |
相对于触发器元素,弹出窗口的自动翻转放置行为。 |
从左到右翻转 ,
顺时针 ,
逆时针 , 或有效位置数组
|
disabled |
false |
Popover显示状态的编程控制。建议与同步修改器一起使用。
|
true , false |
triggers |
'click' |
以空格分隔的事件列表,它将使用内置处理触发打开/关闭popover |
悬停 ,
聚焦 ,
点击 。注意
blur 是一个特殊的用例,用于在下次单击时关闭popover。
|
no-fade |
false |
设置为true 时禁用淡入淡出动画
|
true or false |
delay |
50 |
按指定的毫秒数延迟显示和隐藏弹出窗口。也可以定义为 { show: 100, hide: 400 } 形式的对象,允许不同的显示和隐藏延迟
|
0 及以上,仅整数。 |
offset |
0 |
按指定的像素数移动弹出框的中心。也会影响弹出箭头的位置。 |
任何负整数或正整数 |
container |
null |
要将呈现的弹出窗口附加到的元素字符串ID。如果未找到null 或元素,
则popover将附加到<body> (默认值)
|
文档中任何有效的唯一元素ID。 |
boundary |
'scrollParent' |
弹出窗口将在视觉上受到约束的容器。默认值在大多数情况下应该足够了,但是如果目标元素位于带有溢出滚动条的小容器中,则可能需要更改此值
|
'scrollParent' (默认)、 'viewport' 、
'window' 或对HTML元素的引用。
|
boundary-padding |
5 |
用于定义边界和弹出窗口之间最小距离的像素数。这可以确保popover的容器边缘之间始终有一个小填充。
|
任何正数 |
variant |
null |
弹出窗口的上下文颜色变体 |
任何上下文主题颜色变体名称 |
custom-class |
null |
应用于popover外部包装元素的自定义类名 |
A string |
id |
null |
用于popover根元素的ID。如果没有提供,则会自动生成一个。如果您确实提供了一个ID,那么必须保证它在呈现的页面上是唯一的。
|
有效的唯一元素ID字符串 |
变量和自定义类
BootstrapVue的弹出窗口通过我们的自定义CSS,通过变量
属性支持上下文颜色变体:
引导默认的主题变量有:danger
,
warning
,
success
,
primary
,
secondary
,
info
,
light
,和
dark
。
您可以通过BootstrapSCSS 变量更改或添加其他变量
通过使用自定义类
属性,可以将自定义类应用于popover外部包装器<div>
:
variant
和
custom-class
是被动的,可以在popover打开时更改。
请参阅popover指令文档,了解如何将变量和自定义类应用于指令版本。
显示和隐藏弹出窗口
您可以通过可同步布尔值显示属性手动控制弹出窗口的可见性
。设置为true
将显示弹出窗口,
而设置为false
将隐藏弹出窗口。
通过引用向popover提交'打卡'
和'关闭'
事件也会影响程序控制。
要使弹出窗口显示在初始渲染中,只需在<b-popover>
上添加显示道具:
通过“show”属性或事件调用以编程方式打开的popover只能以编程方式关闭。内置触发器将无法充分工作,因为触发器事件将尝试打开popover,即使它已经打开。
在下面的示例中,当第一个弹出窗口用“打开”事件打开时,需要单击两次按钮才能将其关闭。玩下面的演示来理解这一点。当您希望优雅地处理Popover组件的编程控制和用户交互触发器时,应该禁用内置触发器,并按照第二个Popover演示的那样处理自己的控制。
您还可以使用$root事件触发弹出窗口的显示和隐藏。有关详细信息,请参阅下面的“通过$root
事件隐藏和显示弹出窗口”部分。
以编程方式禁用popover
您可以通过disabled
可同步布尔属性(默认值为false
)
禁用popover,将其设置为true
将禁用popover。如果popover在disabled
设置为
false
时当前可见,则在启用或以编程方式关闭之前,它将保持可见。如果通过$root events禁用/启用了弹出窗口(请参见下文),
则只要您提供了.sync
属性修饰符,您的禁用值就会更新。
通过引用向popover提交'enable'
和'disable'
事件也会影响编程控制。
禁用后,可以通过编程方式(通过show
prop、methods或events)打开弹出窗口
您还可以使用$root
事件触发禁用和启用popover。
有关详细信息,请参阅下面的通过$root events禁用和启用弹出窗口部分。
v-b-popover
指令用法
只需要没有太多标记的快速弹出窗口? 使用v-b-popover
指令:
有关指令用法的详细信息,请参阅v-b-popover
指令文档。
高级 <b-popover>
使用反应性内容
你甚至可以让你的<b-popover>
内容互动。请记住不要使用
或触发器(只使用click
)。
如果绝对必须使用click
以外的触发器(或者希望在第二次单击触发器元素时禁用关闭popover),则可以:
-
监听
<b-popover>
元素上的hide
事件,
并在传递给hide
处理程序的BvEvent
对象上调用
preventDefault()
方法(如果合适);
-
一旦弹出窗口开始打开(通过
show
事件),就禁用触发器元素(如果可能),
并在适当时重新启用它(即通过hide
或
hidden
事件)。
出于实际目的,交互式内容弹出应该是最小的。弹出窗口的最大宽度由引导v4 CSS硬编码为276px
。小屏幕上的高弹出窗口在移动设备(如智能手机)上可能更难处理。
'全局'$ root实例事件
使用$root
实例,可以在组件之外的某个地方发出和侦听事件,
其中使用<b-collapse>
。简而言之,
$root
的行为类似于全局事件发射器和侦听器。
有关$root
实例的详细信息可以在官方Vue文档中找到。
通过$root events隐藏和显示弹出窗口
通过在$root上发出bv::hide::popover
事件,可以关闭(隐藏)所有打开的弹出窗口:
要关闭特定的popover,请将触发器元素的id
或popover的id
(如果是通过id
属性提供的)作为第一个参数传递:
要打开(显示) 特定的popover,请在发出bv::show::popover
事件时将触发器元素的id
或popover的id
(如果是通过id
属性提供的)作为第一个参数传递:
要同时打开所有弹出窗口,请在发出bv::show::popover
事件时省略id
参数。
这些事件适用于Popover的组件版本和指令版本。
注意:触发器元素必须存在于DOM中并且处于可见状态,以便popover实例化和显示
通过$root events禁用和启用弹出窗口
您可以通过在$root上发出bv::disable::popover
事件来禁用所有弹出窗口:
要禁用特定的popover,请将触发器元素的id
或popover的id
(如果是通过id
属性提供的)作为第一个参数传递:
要启用特定的popover,请在发出bv::enable::popover
事件时将触发器元素的
id
或popover的id
(如果是通过id
属性提供的)作为第一个参数传递:
要同时启用所有弹出窗口,请在发出bv::enable::popover
事件时省略id
参数。
这些事件对popover的组件和指令版本都有效。
注意: 触发器元素必须存在于DOM中,才能启用或禁用popover。
通过$ root事件监听弹出窗口更改
要监听任何弹出窗口,请使用:
有关事件的完整列表,请参阅文档的事件部分。
辅助功能
在当前的实现中,popover用作交互组件时不太容易访问。内容可能不会主动读取给屏幕阅读器用户,并且popover标记可能不会位于DOM中的trigger元素附近
(因为popover通常会附加到<body>
的末尾)。
当使用弹出窗口作为交互组件时,如果可能,您应该将焦点转移到弹出窗口中。当popover关闭时,您应该将焦点返回到触发元素
(假设focus
没有用作触发器方法),正如我们在上面的示例中所做的那样。
当用户与popover内容交互时,您可能还希望在popover内容中实现焦点包含(将焦点保持在popover中,直到用户关闭它)。
为键盘和辅助技术用户制作弹出窗口
要允许键盘用户激活弹出窗口,只需将其添加到传统键盘可聚焦和交互式的HTML元素(如链接或表单控件)。
尽管可以通过添加tabindex="0"
属性使任意HTML元素(如<span>
s)成为可聚焦的,
但这将在键盘用户的非交互元素上添加潜在的恼人和令人困惑的制表位,而且大多数辅助技术目前在这种情况下不会公布popover的内容。另外,
不要仅仅依赖于鼠标悬停作为弹出窗口的触发器,因为这将使键盘用户无法触发它们。
虽然您可以通过插槽在弹出窗口中插入丰富、结构化的HTML和/或组件,但我们强烈建议您避免添加过多的内容。弹出窗口当前的工作方式是,一旦显示,
它们的内容就绑定到具有aria-describedby
属性的触发器元素。因此,popover的全部内容将作为一个长的、不间断的流向辅助技术用户公布(读取)。
此外,虽然也可以在popover中包含交互控件(如表单元素或链接),但请注意,当前popover不管理键盘焦点顺序。当键盘用户打开弹出窗口时,
焦点仍停留在触发元素上,并且由于弹出窗口通常不会立即跟随文档结构中的触发器,因此无法保证向前移动/按TAB键会将键盘用户移动到弹出窗口本身。
简而言之,简单地将交互控件添加到popover中可能会使键盘用户和辅助技术用户无法访问/使用这些控件,或者至少会使整个焦点顺序不合逻辑。在这些情况下,请考虑改用<b-modal>
对话框。
组件引用
属性
属性 (Click to sort Ascending) |
类型 |
默认值 |
描述 |
title |
String |
|
放置在弹出窗口标题中的文本 |
target Required |
String or HTMLElement or SVGElement or Function or Object |
|
要触发弹出窗口的元素字符串ID或对元素或组件的引用。 |
triggers |
String or Array |
'click' |
指定哪些触发器将显示弹出窗口。支持的值有“click”、“hover”、“focus”。有关特殊触发器“模糊”和“手动”的信息,请参阅文档 |
placement |
String |
'right' |
弹出框的位置:“顶部”、“底部”、“右侧”、“左侧”、“顶部左侧”、“顶部右侧”、“底部左侧”、“底部右侧”、“左侧顶部”、“左侧底部”、“右侧顶部”、“右侧底部”之一 |
fallback-placement |
String or Array |
'flip' |
当弹出窗口超出边界时使用的位置。请参阅文档以了解更多详细信息 |
variant |
String |
|
将一个引导主题颜色变体应用于组件 |
custom-class |
String |
|
应用于popover根元素的CSS类 |
delay |
Number or Object or String |
50 |
显示和隐藏延迟的值。当指定为数字或字符串时,同时应用于“显示”和“隐藏”。使用对象窗体分别设置显示和隐藏延迟 |
boundary |
String or HTMLElement or Object |
'scrollParent' |
弹出窗口的边界约束:“scrollParent”、“window”、“viewport”或对HTMLElement或组件的引用 |
boundary-padding |
Number or String |
5 |
popover将尝试以指定的像素数远离边界元素的边缘 |
offset |
Number or String |
0 |
箭头中心相对于触发器目标元素的偏移量(像素) |
no-fade |
Boolean |
false |
设置为“true”时,禁用组件上的淡入动画/过渡 |
container |
String or HTMLElement or Object |
|
显示时附加呈现的弹出窗口的容器元素。默认为body元素 |
show |
Boolean |
false |
何时设置将显示弹出窗口 |
noninteractive |
Boolean |
false |
|
disabled |
Boolean |
false |
设置为“true”时,禁用组件的功能并将其置于禁用状态 |
id |
String |
|
用于在渲染的内容上设置“id”属性,并用作根据需要生成任何其他元素ID的基础 |
content |
String |
|
要放置在弹出窗口主体中的文本 |
插槽
插槽名称 |
描述 |
title |
标题的可选位置(HTML/components supported) |
default |
内容槽 (HTML/components supported) |
事件
事件 |
参数 |
描述 |
show |
bvEvent - bvEvent object
|
当弹出窗口即将显示时发出。可取消。调用bvEvent.preventDefault()取消显示。 |
shown |
bvEvent - bvEvent object
|
显示popover时发出 |
hide |
bvEvent - bvEvent object
|
当popover即将隐藏时发出。可取消。调用bvEvent.preventDefault()取消隐藏。 |
hidden |
bvEvent - bvEvent object
|
隐藏popover时发出 |
enabled |
bvEvent - bvEvent object
|
启用popover时发出 |
disabled |
bvEvent - bvEvent object
|
当popover被禁用时发出 |
bv::popover::show |
bvEvent - bvEvent object
|
将要显示popover时在$root上发出。可取消。调用bvEvent.preventDefault()取消显示。 |
bv::popover::shown |
bvEvent - bvEvent object
|
显示popover时在$root上发出 |
bv::popover::hide |
bvEvent - bvEvent object
|
当popover即将隐藏时在$root上发出。可取消。调用bvEvent.preventDefault()取消隐藏。 |
bv::popover::hidden |
bvEvent - bvEvent object
|
隐藏popover时在$root上发出 |
bv::popover::enabled |
bvEvent - bvEvent object
|
启用popover时在$root上发出 |
bv::popover::disabled |
bvEvent - bvEvent object
|
当popover被禁用时在$root上发出 |
$root
事件监听器
您可以通过在$root上发出以下事件来控制<b-popover>
:
事件 |
参数 |
描述 |
bv::hide::popover |
id - (optional), popover id to hide
|
在$root上发出此事件时关闭(隐藏)所有或特定的打开弹出窗口 |
bv::show::popover |
id - (optional), popover id to show
|
在$root上发出此事件时打开(显示)所有或特定的弹出窗口 |
bv::disable::popover |
id - (optional), popover id to disable
|
在$root上发出此事件时禁用所有或特定的popover |
bv::enable::popover |
id - (optional), popover id to enable
|
在$root上发出此事件时启用所有或特定的popover |
导入单个组件
您可以通过以下命名的导出将单个组件导入到项目中:
组件 |
命名输出 |
导入路径 |
<b-popover> |
BPopover |
bootstrap-vue |
示例:
导入为Vue.js插件
该插件包括上面列出的所有单个组件。插件还包括任何组件别名。
命名输出 |
导入路径 |
PopoverPlugin |
bootstrap-vue |
此插件还自动包含以下插件:
示例: