组件
ShadcnHoverCard
悬浮卡片:悬停触发的预览卡片,带打开 / 关闭延时,指针可移进卡片。

悬浮卡片(shadcn/ui Hover Card,底层是 Base UI 的 Preview Card)。鼠标停在触发项上 一小会儿,浮出一张预览卡片;移开后过一会儿才收起,这段时间里指针可以直接移进卡片里 读内容。典型场景:用户名 → 个人简介、链接 → 目标预览、术语 → 释义。
对齐官方 Base UI 版 hover-card.json。
用法
ShadcnHoverCard {
ShadcnHoverCardTrigger { text: qsTr("@bailicangdu") }
ShadcnHoverCardContent {
RowLayout {
spacing: 10
ShadcnAvatar { iconName: "user" }
Column {
spacing: 2
Text { text: qsTr("白里苍渡"); font.weight: Font.Medium }
Text { text: qsTr("@bailicangdu · 前端工程师"); color: theme.mutedForeground }
}
}
Text { text: qsTr("专注 Qt / QML 与组件库设计。"); wrapMode: Text.WordWrap }
}
}
Trigger 默认是 ShadcnButton.Variant.Link(官方 hover-card 触发项就是带下划线的链接),
可换任意 variant。
延时(HoverCard 的灵魂)
| 属性 | 默认 | 说明 |
|---|---|---|
delay | 600 | 指针停在触发项上多久才打开。防「扫过一串链接」乱弹 |
closeDelay | 300 | 离开后多久才关。给「从链接移进卡片」那段空白留缓冲 |
默认值取自 Base UI PreviewCard(OPEN_DELAY = 600 / CLOSE_DELAY = 300)。行为:
- 指针进入触发项 → 起
delay计时;计时未到就离开 → 取消,不弹(快速划过干净) - 已打开后离开 → 起
closeDelay计时;计时内指针移进卡片 → 取消关闭,保持打开 delay/closeDelay可按需调小(密集列表预览)或调大(更克制)
API
ShadcnHoverCard(根)
| 属性 / 只读 | 默认 | 说明 |
|---|---|---|
open | false | 强制显示(演示 / 截图等无鼠标场景,忽略悬停计时) |
delay | 600 | 打开延时 ms |
closeDelay | 300 | 关闭延时 ms |
reducedMotion | false | 减弱动画:弹层进出时长归零 |
hovered | — | 悬停计时是否已到位(只读) |
showing | — | 实际显示状态 = open 或 hovered(只读) |
pointerInside | — | 指针当前是否在触发项或卡片之上(只读) |
trigger / content | — | 收集到的子件(只读) |
placement | — | 定位结果(只读) |
popup | — | 弹层本体(只读) |
transitionDurationMs | 100 | 弹层过渡实际时长(只读) |
ShadcnHoverCardContent
继承 ShadcnPopoverContent,样式同源,只有三处默认值不同(registry 核实):
| 属性 | 默认 | 说明 |
|---|---|---|
panelWidth | 256 | registry w-64(Popover 是 w-72=288) |
contentSpacing | 0 | hover-card 不是 flex-col,无 gap-2.5 |
alignOffset | 4 | registry 默认 alignOffset = 4 |
side / align / sideOffset | bottom / center / 4 | 同 Popover |
定位与视觉
与 Popover 共用同一套弹层件(ShadcnPopoverPopup):side / align 透传、贴边
自动翻转、fade + zoom-95 100ms、rounded-lg + bg-popover + p-2.5 +
ring-1 ring-foreground/10 + shadow-md 全部一致。
交互
- 悬停触发项(够久):打开;移开(超时):关闭
- 按 Esc / 点击外部:立即关闭,且本轮不再自动重开(指针还停在触发项上也不会弹回, 必须移开再移回来)—— 避免「关不掉」的抖动
- HoverCard 不抢焦点:它用
Shortcut接 Esc,而不是把焦点从页面里的输入框夺走 (这是与 Popover 唯一的行为差异,Popover 打开时会拿焦点)
相关
- 用户名预览、链接目标预览、术语释义、地图缩略
- Popover:点击触发的自由面板(同一套弹层)
