QtShadcn
组件

ShadcnEmpty

空状态占位:EmptyHeader / EmptyMedia / EmptyTitle / EmptyDescription / EmptyContent 组合。

空状态占位,纯组合组件,对齐 shadcn/ui v4:

Empty
├── EmptyHeader
│   ├── EmptyMedia
│   ├── EmptyTitle
│   └── EmptyDescription
└── EmptyContent

用法

ShadcnEmpty {
    width: 400
    height: 260
    bordered: true                      // 需要虚线框时打开(见下方「虚线边框」)

    ShadcnEmptyHeader {
        ShadcnEmptyMedia {
            variant: ShadcnEmptyMedia.Variant.Icon
            iconName: "inbox"
        }
        ShadcnEmptyTitle { text: qsTr("暂无数据") }
        ShadcnEmptyDescription { text: qsTr("还没有任何内容,先创建一条吧。") }
    }
    ShadcnEmptyContent {
        ShadcnButton { text: qsTr("新建") }
    }
}

最小结构(只放标题):

ShadcnEmpty {
    ShadcnEmptyTitle { text: qsTr("暂无数据") }
}

虚线边框:Qt 没有直接的虚线 border

Empty 的规范是 border-dashed,但 Qt 的 Rectangle 只支持实线 border (border.width / border.color,无 dash 样式;BorderImage 也不支持描边)。 本组件的方案是用 Shape + ShapePath 画圆角矩形描边:

Shape {
    ShapePath {
        strokeStyle: ShapePath.DashLine
        dashPattern: [4, 4]        // [实线, 空白]
    }
}

与 ShadcnSpinner 用 Shape 画弧线同一套(仓库明文禁 Canvas 动画;Shape 直接进 场景图,不走 QML 主线程重绘)。两个必须处理的细节:

  • 路径内缩半个线宽:Shape 的描边以路径为中线向两侧各展开 strokeWidth/2, 不内缩会有一半画到容器外被裁掉
  • dash 长度会乘线宽(QPainter 规则):线宽 1 时 [4,4] 才是 4px 实 4px 空

tests/qml/tst_ShadcnEmpty.qml 里有像素级断言:抓图后逐像素扫上边和左边, 要求出现多段实线且覆盖率明显小于 100%(实线冒充虚线会直接 FAIL)。

为什么默认 bordered: false

官方 cn-empty 的类名是 border-dashed,没有写宽度(border / border-2 之类); Tailwind preflight 把 border-width 归零,所以官方默认渲染其实没有可见描边。 官方文档里的「Outlined」示例才额外加 border 类(border border-dashed)。

Qt 侧照此对齐:默认不描边,需要虚线框时 bordered: true——正好对应官方那个 border 类,语义一一对应,不做「默认实线」的妥协。

API

ShadcnEmpty

属性默认说明
borderedfalse是否绘制描边(官方默认无边,见上)
dashedtrue描边是否虚线;false = 实线(对应只加 border)
borderColortheme.border描边颜色
borderWidth1描边线宽
dashPattern[4, 4]虚线节拍 [实线, 空白],单位 px(实际长度 = 值 × borderWidth)
padding24内边距,p-6
spacing16直接子项间距,gap-4
color"transparent"背景;需要底色时如 theme.muted(官方 bg-muted/30)
radiustheme.radiusXl圆角,rounded-xl
content—默认属性,收子项进内部 ColumnLayout

子组件

组件对应官方类说明
ShadcnEmptyHeadermax-w-sm flex-col items-center gap-2头部,最大宽 384、间距 8、整体居中
ShadcnEmptyMediamb-2 + variant视觉元素(图标 / 头像),底部留 8px
ShadcnEmptyTitletext-sm font-medium tracking-tight标题,14px / 500 / 字距 -0.35
ShadcnEmptyDescriptiontext-sm/relaxed text-muted-foreground描述,14px / 行高 1.625 / 次要色
ShadcnEmptyContentmax-w-sm flex-col items-center gap-2.5 text-sm操作区,最大宽 384、间距 10

ShadcnEmptyMedia

属性默认说明
variantVariant.DefaultDefault 透明;Icon = size-8(32) 带底色方块
iconName""便捷用法:给 lucide 图标名自动渲染 ShadcnIcon
iconColortheme.foreground图标颜色
content—默认属性,可塞任意单元素(如 ShadcnAvatar)

Icon 变体额外细节:rounded-lg(theme.radiusLg)+ bg-muted + 内部 svg size-4(16)。 Default 变体不受 size-4 限制,用 lucide 设计尺寸 24。

布局

内容列(内部 ColumnLayout)水平铺满内边距内区域,垂直居中(justify-center); 内容高于容器时退回顶部 padding 起点,不越界。

直接子项默认水平居中(对应 CSS 的 items-center),包括用户自己塞进来的固定宽子项; 子项自己写过 Layout.alignment 时尊重它。所以:

  • 不需要给子项包一层居中容器,也不要给 EmptyHeader / EmptyContent 设 width
  • 不要用裸 x / y 给直接子项定位,位置由布局接管

视觉

  • rounded-xl = theme.radiusXl(radius × 1.4),不写死像素
  • 无背景(官方 cn-empty 没有背景类),需要时用 color
  • 虚线:theme.border 1px,4px/4px 节拍

相关

  • 与 ShadcnCard 组合做「卡片内空列表」
  • ShadcnSkeleton 做加载态、ShadcnEmpty 做空态、列表本体做有数据态
  • ShadcnIcon 提供 lucide 图标(iconName 取自 IconRegistry)
Copyright © 2026