ShadcnEmpty

空状态占位,纯组合组件,对齐 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
| 属性 | 默认 | 说明 |
|---|---|---|
bordered | false | 是否绘制描边(官方默认无边,见上) |
dashed | true | 描边是否虚线;false = 实线(对应只加 border) |
borderColor | theme.border | 描边颜色 |
borderWidth | 1 | 描边线宽 |
dashPattern | [4, 4] | 虚线节拍 [实线, 空白],单位 px(实际长度 = 值 × borderWidth) |
padding | 24 | 内边距,p-6 |
spacing | 16 | 直接子项间距,gap-4 |
color | "transparent" | 背景;需要底色时如 theme.muted(官方 bg-muted/30) |
radius | theme.radiusXl | 圆角,rounded-xl |
content | — | 默认属性,收子项进内部 ColumnLayout |
子组件
| 组件 | 对应官方类 | 说明 |
|---|---|---|
ShadcnEmptyHeader | max-w-sm flex-col items-center gap-2 | 头部,最大宽 384、间距 8、整体居中 |
ShadcnEmptyMedia | mb-2 + variant | 视觉元素(图标 / 头像),底部留 8px |
ShadcnEmptyTitle | text-sm font-medium tracking-tight | 标题,14px / 500 / 字距 -0.35 |
ShadcnEmptyDescription | text-sm/relaxed text-muted-foreground | 描述,14px / 行高 1.625 / 次要色 |
ShadcnEmptyContent | max-w-sm flex-col items-center gap-2.5 text-sm | 操作区,最大宽 384、间距 10 |
ShadcnEmptyMedia
| 属性 | 默认 | 说明 |
|---|---|---|
variant | Variant.Default | Default 透明;Icon = size-8(32) 带底色方块 |
iconName | "" | 便捷用法:给 lucide 图标名自动渲染 ShadcnIcon |
iconColor | theme.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.border1px,4px/4px 节拍
相关
- 与
ShadcnCard组合做「卡片内空列表」 ShadcnSkeleton做加载态、ShadcnEmpty做空态、列表本体做有数据态ShadcnIcon提供 lucide 图标(iconName取自IconRegistry)
