QtShadcn
组件

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 的灵魂)

属性默认说明
delay600指针停在触发项上多久才打开。防「扫过一串链接」乱弹
closeDelay300离开后多久才关。给「从链接移进卡片」那段空白留缓冲

默认值取自 Base UI PreviewCard(OPEN_DELAY = 600 / CLOSE_DELAY = 300)。行为:

  • 指针进入触发项 → 起 delay 计时;计时未到就离开 → 取消,不弹(快速划过干净)
  • 已打开后离开 → 起 closeDelay 计时;计时内指针移进卡片 → 取消关闭,保持打开
  • delay / closeDelay 可按需调小(密集列表预览)或调大(更克制)

API

ShadcnHoverCard(根)

属性 / 只读默认说明
openfalse强制显示(演示 / 截图等无鼠标场景,忽略悬停计时)
delay600打开延时 ms
closeDelay300关闭延时 ms
reducedMotionfalse减弱动画:弹层进出时长归零
hovered—悬停计时是否已到位(只读)
showing—实际显示状态 = open 或 hovered(只读)
pointerInside—指针当前是否在触发项或卡片之上(只读)
trigger / content—收集到的子件(只读)
placement—定位结果(只读)
popup—弹层本体(只读)
transitionDurationMs100弹层过渡实际时长(只读)

ShadcnHoverCardContent

继承 ShadcnPopoverContent,样式同源,只有三处默认值不同(registry 核实):

属性默认说明
panelWidth256registry w-64(Popover 是 w-72=288)
contentSpacing0hover-card 不是 flex-col,无 gap-2.5
alignOffset4registry 默认 alignOffset = 4
side / align / sideOffsetbottom / 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:点击触发的自由面板(同一套弹层)
Copyright © 2026