Skip to content

Hover Card 悬浮卡片

基于 BrConfigProvider 实现全局主题配置,支持自适应定位、懒渲染和键盘导航的企业级悬浮卡片组件,可无缝集成 BrTableBrList 等组件。

组件特性

  • 🎯 自适应定位:智能计算空间,支持自动避障和多方向(上/下/左/右)弹出。
  • 无缝集成:可与 BrTableBrListBrAvatar 等组件完美组合,处理复杂交互。
  • 🎨 主题定制:基于 BrConfigProvider 实现全局定制,支持 TailwindCSS 局部覆写。
  • ⌨️ 可访问性:内置键盘导航(Tab 切换、ESC 关闭)、延迟控制,避免误触。
  • 📦 多实例管理:自带 HoverCardManager 提供全局 z-index 层级自动递增。

基础使用

最基础的悬浮卡片,鼠标悬浮在触发元素上时显示。

Example

与头像 (Avatar) 集成

常用于用户信息展示的场景,在头像上悬浮以显示用户的详细信息。

VU
Example

与表格 (Table) 集成

在表格行悬浮时展示更多扩展信息或操作表单。

Invoice
Status
Method
Amount
INV001
Paid
Credit Card$250.00
INV002
Pending
PayPal$150.00
Example

表单交互 (键盘导航支持)

悬浮卡片内置了焦点管理功能,通过 Tab 键可直接切换到卡片内的输入框进行交互,并支持通过 ESC 键快捷关闭卡片。

Example

主题定制

支持使用 BrConfigProvider 对 HoverCard 进行全局配置,或者使用 TailwindCSS 实现局部样式隔离定制。

Example

API 说明

BrHoverCard

参数类型默认值说明
defaultOpenbooleanfalse初始状态下是否打开
openbooleanfalse受控的打开状态
openDelaynumber700触发打开的延迟时间(毫秒),避免误触
closeDelaynumber300触发关闭的延迟时间(毫秒)
@update:open(value: boolean) => void-打开状态改变时的回调

BrHoverCardTrigger

包含子元素的包装器,默认使用 asChild

BrHoverCardContent

参数类型默认值说明
placement'top' | 'bottom' | 'left' | 'right' | 'top-start' 等 12 种'bottom'悬浮卡片相对触发器的位置
sideOffsetnumber4悬浮卡片距离触发器的偏移量
loadingbooleanfalse是否显示加载态占位
emptybooleanfalse是否显示空数据占位
zIndexnumber自动递增卡片的 z-index 层级,默认通过 HoverCardManager 自动管理
isolatedbooleanfalse是否开启样式隔离类,避免全局样式污染

HoverCardManager

静态管理类,用于管理悬浮卡片的全局状态和层级。

方法返回类型说明
nextZIndex()number获取下一个自增的 z-index,用于处理多实例嵌套层级