QtShadcn
组件

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(根)

属性 / 只读默认说明
openfalse是否打开(双向;点外 / Esc 关闭后自动复位)
reducedMotionfalse减弱动画:弹层进出时长归零
trigger—收集到的 Trigger(只读)
content—收集到的 Content(只读)
hovered—内容区是否被悬停(只读)
placement—ShadcnPopupPosition 定位结果(只读)
popup—弹层本体 QQC.Popup(只读)
transitionDurationMs100弹层过渡实际时长(token 折算后,只读)

ShadcnPopoverTrigger

就是 ShadcnButton,支持其全部 variant / size / iconName。

ShadcnPopoverContent

属性默认说明
side"bottom"期望方向
align"center"横向对齐
alignOffset0横向对齐偏移
sideOffset4与触发项的间距
panelWidth288面板宽度(registry w-72)
panelPadding10内边距(registry p-2.5)
contentSpacing10子项间距(registry gap-2.5)

ShadcnPopoverHeader / Title / Description

  • Header:Column,spacing = 2(registry gap-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
Copyright © 2026