QtShadcn
快速开始

里程碑

组件开发路线图与当前进度。
阶段内容状态
M0仓库骨架:根 CMakeLists + src/qml 模块 + src/core + showcase 空应用✅ 完成
M1Theme 基础层:C++ ThemeManager + light/dark tokens + QtShadcnTheme + showcase 色板页✅ 完成
M2Button 组件(variant / size / disabled / loading)✅ 完成
M3布局与反馈:Card / Alert / Dialog / 表单控件 / Badge / Label / Separator / Skeleton / Spinner✅ 主体完成(剩余 4 项拆至 #13:Alert Dialog / Drawer·Sheet / Toast / Typography)
M4Icon 系统 + 内容展示 + 组合交互 + Animations🔄 进行中(Icon ✅ 已关闭 / 内容展示 3/6 / 组合交互未开始 / Animations 见 #14)
M5C++ Models / Table(WindowManager 延后)🔄 进行中(Table + TableModel ✅ / Calendar·DatePicker·Chart·Models 基类待做)
M6文档站完善 + README + 发布🔄 进行中(文档内容 + find_package + Release ✅ / 文档站尚未部署)

每个里程碑独立可构建、可运行验证(showcase 承载)。进度以 GitHub Issues 为准,本表只做概览。

工程质量

不绑里程碑、持续推进的质量基线(详见 .qmllint.ini 与 tests/):

项状态说明
QML 静态检查✅ 0 警告qmllint + .qmllint.ini,MaxWarnings=0,无任何降级例外
QML 组件测试🔄 15 / 30Qt Quick Test,每个 tst_*.qml 独立一个 ctest 项(30 = 组件目录 51 个文件减去 21 个纯子件)
C++ 单元测试✅ 3 项ThemeManager / IconRegistry / ShadcnTableModel
打包消费验证✅make consumer-smoke:安装前缀 + 独立工程 find_package(QtShadcn),CI 每次跑

lint 门禁只看最低支持版本(CI 跑 Qt 6.8)。本地 Qt 6.11 全绿不代表 6.8 全绿 —— 引用 QtQuick 的成员前先查 plugins.qmltypes 的 revision,>= 1536 即 6.9+,一律不能用。

组件计划(GitHub issues)

每批一个组件,对应一个 GitHub issue,实现完关闭对应 issue。见 组件开发流程。

约定:一批组件里主体交付即关闭,未完成项拆成独立 issue 继续跟踪,不让已完成的部分长期挂着。 例:#3 布局与反馈(主体 8 项已交付)关闭后剩余 4 项见 #13;#6 Icon + Animations(Icon 5/5 已交付)关闭后 Animations 见 #14。

当前已落地组件

组件说明
QtShadcnTheme声明式主题入口(M1)
ShadcnButton6 variant × 5 size,loading / 键盘焦点环(M2)
ShadcnButtonGroup按钮组:合并边框 + 分隔线
ShadcnToggle / ShadcnToggleGroup切换按钮,支持 exclusive 单选
ShadcnSpinner加载指示器(Button loading 内部使用)
ShadcnCard纯组合组件:CardHeader / Content / Footer,size default/sm(M3)
ShadcnInput基于 QQC.TextField:32px 高(h-8)+ rounded-lg 派生圆角 + 聚焦环
ShadcnBadge6 variant,胶囊形,destructive 透明底红字(v4)
ShadcnSwitch32×18 / 24×14 双尺寸(v4),胶囊轨道 + 滑块动画
ShadcnTabsTabsList + TabsTrigger + TabsContent,default/line 双 variant
ShadcnDialog居中 384px(max-w-sm)+ 1px ring(v4 无阴影)+ fade/zoom 动画 + 自定义 header/footer
ShadcnIconlucide 图标:本地精选 74 个 + 远程兜底(CDN 拉取 + 磁盘缓存),随主题变色(M4)
IconRegistryC++ 图标注册表:qrc 加载 + 远程下载 + 缓存,dataUrl(name, color) 供 QML 直接用
ShadcnTextarea基于 QQC.TextArea:min-h 64 + rounded-lg 派生圆角 + 聚焦环(M3 收尾)
ShadcnCheckbox16px + rounded 5px,选中 primary 底 + check 图标
ShadcnRadio / ShadcnRadioGroup16px 正圆单选组,primary 底 + 内圆点
ShadcnSlider8px 轨道 + primary range + 白色胶囊 thumb(hover/focus ring)
ShadcnProgress12px muted 轨道 + primary 指示条(宽度动画,可选百分比)
ShadcnSelect基于 QQC.ComboBox:32/28px trigger(h-8/h-7)+ chevron-down + popover 弹层(hover accent / 选中 check)
ShadcnInputGroup输入框前缀/后缀(icon 或文本),padding 自动让位
ShadcnAvatar头像:图片 / 文字首字母兜底,size 可选(M4 同期补充)
ShadcnStatusDot状态点:色 + 可选 pulse 动画,标注在线/离线/忙碌等(M4 同期补充)
ShadcnTable表格:QQC.TableView + ShadcnTableModel,表头排序 + 行选中(M5)
ShadcnTableModelC++ QAbstractTableModel,rows/columns + cellData/sortBy/updateRow(M5)
ShadcnSeparator分隔线:水平 / 竖直 / 带文字(M6)
ShadcnLabel语义化文本标签:3 variant × 3 size(M6)
ShadcnTooltip悬停提示:QQC.ToolTip + 主题样式(M6)
ShadcnAlert提示框:4 variant + 图标 + 标题 + 描述(M6)
ShadcnSkeleton骨架屏:闪烁动画占位块(M6)
ShadcnKbd键盘快捷键标签:等宽字体 + 边框(M6)
ShadcnDropdownMenu下拉菜单:Trigger + Content + Item 组合(M6)
ShadcnScrollArea滚动区域:Flickable + token 化滚动条,竖直 / 横向 / 双向
ShadcnScrollBar滚动条:轨道 10px + thumb 8px + 全圆角,可 attach 任意 Flickable / TableView
Copyright © 2026