组件
ShadcnPopover
弹出层:点击触发的气泡面板,Trigger + Content 组合,可放任意内容。

弹出层(shadcn/ui Popover)。点击 Trigger 开合,Content 里可以放任意业务 QML
(表单、输入框、日历……)。与 DropdownMenu 的区别:菜单是「选项列表」,Popover 是
「一块自由面板」。对齐官方 Base UI 版 popover.json。
用法
ShadcnPopover {
ShadcnPopoverTrigger { text: qsTr("编辑资料"); variant: ShadcnButton.Variant.Outline }
ShadcnPopoverContent {
ShadcnPopoverHeader {
ShadcnPopoverTitle { text: qsTr("更新头像") }
ShadcnPopoverDescription { text: qsTr("头像将显示在你的个人资料中。") }
}
ShadcnInput { placeholderText: qsTr("输入新头像 URL") }
ShadcnButton { text: qsTr("提交") }
}
}
程序化开合(受控):
ShadcnPopover {
id: pop
open: mySwitch.checked // 双向:点外 / Esc 关闭会把它复位
...
}
定位
side / align / alignOffset / sideOffset 挂在 Content 上(官方就是这么设计
的),根组件读走后透传给 ShadcnPopupPosition:
ShadcnPopoverContent {
side: "top" // "bottom"(默认)| "top"
align: "start" // "center"(默认)| "start" | "end"
alignOffset: 0 // 横向再偏移
sideOffset: 4 // 与触发项的间距
}
- 贴边自动翻转:触发项贴近窗口底沿、下方放不下时,面板自动翻到上方。读
popover.placement.resolvedSide("top"/"bottom")可拿到最终方向。 - 两侧都放不下:取空间大的一侧并把面板高度钳到可用空间(
placement.clamped), 溢出部分裁掉。
API
ShadcnPopover(根)
| 属性 / 只读 | 默认 | 说明 |
|---|---|---|
open | false | 是否打开(双向;点外 / Esc 关闭后自动复位) |
reducedMotion | false | 减弱动画:弹层进出时长归零 |
trigger | — | 收集到的 Trigger(只读) |
content | — | 收集到的 Content(只读) |
hovered | — | 内容区是否被悬停(只读) |
placement | — | ShadcnPopupPosition 定位结果(只读) |
popup | — | 弹层本体 QQC.Popup(只读) |
transitionDurationMs | 100 | 弹层过渡实际时长(token 折算后,只读) |
ShadcnPopoverTrigger
就是 ShadcnButton,支持其全部 variant / size / iconName。
ShadcnPopoverContent
| 属性 | 默认 | 说明 |
|---|---|---|
side | "bottom" | 期望方向 |
align | "center" | 横向对齐 |
alignOffset | 0 | 横向对齐偏移 |
sideOffset | 4 | 与触发项的间距 |
panelWidth | 288 | 面板宽度(registry w-72) |
panelPadding | 10 | 内边距(registry p-2.5) |
contentSpacing | 10 | 子项间距(registry gap-2.5) |
ShadcnPopoverHeader / Title / Description
- Header:
Column,spacing = 2(registrygap-0.5) - Title:
font-medium+popoverForeground - Description:
mutedForeground
视觉
对齐 registry popover-content:w-72 + rounded-lg(theme.radiusLg)+
bg-popover + p-2.5 + gap-2.5 + text-sm + ring-1 ring-foreground/10 +
shadow-md。进出动画 fade + zoom-95,100ms(ShadcnFadeZoomTransition)。
shadow-md 与 ring-1 都在官方 class 里(这一版 popover / hover-card 仍带
shadow,不像 Dialog 那样用 ring 取代了 shadow)。阴影走 layer + MultiEffect,
offscreen 软件渲染不支持 GPU 特效,故截图模式(QTSHADCN_SCREENSHOT=1)下自动关闭
layer,与 ShadcnDropdownMenuContent 同一处理。
交互
- 点击 Trigger:开 / 合
- 点击外部 / 按 Esc:关闭(
open自动复位) - 弹层渲染在 Window Overlay 层,天然置顶;父链任一不可见时弹层同步隐藏 (避免隐藏页里的浮层串到别的页面)
相关
- 表单气泡、筛选面板、日期选择、行内编辑
- Hover Card:同一套弹层,改成悬停触发
- DropdownMenu:选项列表用菜单,自由面板用 Popover
