使用场景
Popover 气泡卡片是由用户自主打开的临时性浮层卡片,能够承载一些额外内容和交互行为而不影响原页面。
和 Tooltip 的区别是,它可以承载更复杂的内容,而不仅仅是提示文本。
代码演示
如何引入
基本使用
将浮层的触发器 Trigger 作为
children
,使用 Popover 包裹(如下的例子中触发器为 Tag 元素)。浮层内容通过content
传入弹出位置
支持通过
position
设置浮层弹出方向,共支持十二个方向。受控显示
设置
trigger='custom'
,此场景下,Popover 的显示与否完全受到参数 visible
的控制。显示小三角
版本:>= 0.19.0
通过设置
showArrow
, Popover 同样也支持展示一个小三角。这种模式下浮层会拥有一个默认的样式,你可以通过传递 style 参数来覆盖掉。
指向元素中心
版本:>= 0.34.0
在显示小三角的条件(
showArrow=true
)下,可以传入 arrowPointAtCenter=true
使得小三角始终指向元素中心位置。设置浮层背景色
如果你需要定制浮层的背景色或边框颜色,请务必单独声明
style
中的 backgroundColor
和 borderColor
属性,这样能够使得“小三角”也能应用相同的背景色和边框颜色。初始化弹出层焦点位置
Popover content 支持传入函数,它的入参是一个对象,将
initialFocusRef
绑定在可聚焦 DOM 或组件上,打开面板时会自动聚焦在该位置。搭配 Tooltip 或 Popconfirm 使用
请参考搭配使用
API 参考
属性 | 说明 | 类型 | 默认值 | 版本 |
---|---|---|---|---|
autoAdjustOverflow | 是否自动调整弹出层展开方向,用于边缘遮挡时自动调整展开方向 | boolean | true | |
arrowPointAtCenter | “小三角”是否指向元素中心,需要同时传入"showArrow=true" | boolean | true | 0.34.0 |
closeOnEsc | 在 trigger 或 弹出层按 Esc 键是否关闭面板,受控时不生效 | boolean | true | 2.8.0 |
content | 显示的内容(函数类型,2.8.0 版本支持) | ReactNode | ({ initialFocusRef }) => ReactNode | ||
clickToHide | 点击弹出层及内部任一元素时是否自动关闭弹层 | boolean | false | 0.24.0 |
getPopupContainer | 指定父级 DOM,弹层将会渲染至该 DOM 中,自定义需要设置 position: relative | function():HTMLElement | () => document.body | |
guardFocus | 当焦点处于弹出层内时,切换 Tab 是否让焦点在弹出层内循环 | boolean | true | 2.8.0 |
mouseEnterDelay | 鼠标移入后,延迟显示的时间,单位毫秒(仅当 trigger 为 hover/focus 时生效) | number | 50 | |
mouseLeaveDelay | 鼠标移出后,延迟消失的时间,单位毫秒(仅当 trigger 为 hover/focus 时生效) | number | 50 | |
rePosKey | 可以更新该项值手动触发弹出层的重新定位 | string|number | ||
returnFocusOnClose | 按下 Esc 键后,焦点是否回到 trigger 上,只有设置 trigger 为 click 时生效 | boolean | true | 2.8.0 |
position | 方向,可选值:top ,topLeft ,topRight ,left ,leftTop ,leftBottom ,right ,rightTop ,rightBottom ,bottom ,bottomLeft ,bottomRight | string | "bottom" | |
spacing | 弹出层与 children 元素的距离,单位 px | number | 4(showArrow=false 时) 10(showArrow=true 时) | |
showArrow | 是否显示“小三角” | boolean | ||
stopPropagation | 是否阻止弹出层上的点击事件冒泡 | boolean | false | 0.34.0 |
trigger | 触发方式,可选值:hover , focus , click , custom | string | 'hover' | |
visible | 是否显示,配合trigger='custom'可实现完全受控 | boolean | ||
zIndex | 弹出层 z-index 值 | number | 1030 | |
onClickOutSide | 当弹出层处于展示状态,点击非Children、非浮层内部区域时的回调(仅trigger为custom、click时有效) | function(e:event) | 2.1.0 | |
onEscKeyDown | 在 trigger 或 弹出层按 Esc 键时调用 | function(e:event) | 2.8.0 | |
onVisibleChange | 弹出层展示/隐藏时触发的回调 | function(isVisble:boolean) |
Accessibility
ARIA
- 关于 role
- 当 Popover 的 trigger 为 click、custom时,Popover的 content 具有
dialog
role - 当trigger为hover时,Popover的content 具有
tooltip
role
- 当 Popover 的 trigger 为 click、custom时,Popover的 content 具有
- Popover 的 content
- content 的 wrapper 会被自动添加
id
属性
- content 的 wrapper 会被自动添加
- Popover 的 children
- 会被自动添加 aria-expanded 属性,当 Popover 可见时,属性值为
true
,不可见时为false
- 会被自动添加 aria-haspopup 属性,为
dialog
- 会被自动添加 aria-controls 属性,为 content 的 wrapper 的 id
- 会被自动添加 aria-expanded 属性,当 Popover 可见时,属性值为
键盘和焦点
- Popover 触发方式设置为 hover 时:鼠标悬浮或聚焦时打开 Popover
- Popover 触发方式设置为 click 时:点击触发器或聚焦时并使用 Enter 键打开 Popover
- Popover 激活后,按下方向键 ⬇️ 将焦点移动到 Popover 上,此时焦点默认处于 Popover 中第一个可交互元素上,用户也可自定义焦点位置(若 Popover 内无可交互元素则表现为无响应)
- 焦点处于 Popover 内时使用 Tab 键,焦点会在 Popover 内循环,使用 Shift + Tab 会反方向移动焦点
- 键盘用户能够通过按 Esc 关闭 Popover,关闭后焦点返回到触发器上(仅当 trigger 为 click 时)