快速开始
里程碑
组件开发路线图与当前进度。
| 阶段 | 内容 | 状态 |
|---|---|---|
| M0 | 仓库骨架:根 CMakeLists + src/qml 模块 + src/core + showcase 空应用 | ✅ 完成 |
| M1 | Theme 基础层:C++ ThemeManager + light/dark tokens + QtShadcnTheme + showcase 色板页 | ✅ 完成 |
| M2 | Button 组件(variant / size / disabled / loading) | ✅ 完成 |
| M3 | 布局与反馈:Card / Alert / Dialog / 表单控件 / Badge / Label / Separator / Skeleton / Spinner | ✅ 主体完成(剩余 4 项拆至 #13:Alert Dialog / Drawer·Sheet / Toast / Typography) |
| M4 | Icon 系统 + 内容展示 + 组合交互 + Animations | 🔄 进行中(Icon ✅ 已关闭 / 内容展示 3/6 / 组合交互未开始 / Animations 见 #14) |
| M5 | C++ 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 / 30 | Qt 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) |
ShadcnButton | 6 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 派生圆角 + 聚焦环 |
ShadcnBadge | 6 variant,胶囊形,destructive 透明底红字(v4) |
ShadcnSwitch | 32×18 / 24×14 双尺寸(v4),胶囊轨道 + 滑块动画 |
ShadcnTabs | TabsList + TabsTrigger + TabsContent,default/line 双 variant |
ShadcnDialog | 居中 384px(max-w-sm)+ 1px ring(v4 无阴影)+ fade/zoom 动画 + 自定义 header/footer |
ShadcnIcon | lucide 图标:本地精选 74 个 + 远程兜底(CDN 拉取 + 磁盘缓存),随主题变色(M4) |
IconRegistry | C++ 图标注册表:qrc 加载 + 远程下载 + 缓存,dataUrl(name, color) 供 QML 直接用 |
ShadcnTextarea | 基于 QQC.TextArea:min-h 64 + rounded-lg 派生圆角 + 聚焦环(M3 收尾) |
ShadcnCheckbox | 16px + rounded 5px,选中 primary 底 + check 图标 |
ShadcnRadio / ShadcnRadioGroup | 16px 正圆单选组,primary 底 + 内圆点 |
ShadcnSlider | 8px 轨道 + primary range + 白色胶囊 thumb(hover/focus ring) |
ShadcnProgress | 12px 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) |
ShadcnTableModel | C++ 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 |
