QtShadcn
快速开始

项目结构

仓库目录结构与 QML 模块约定。
qtshadcn/
├── CMakeLists.txt              # 根构建
├── Makefile                    # make build / make run 快捷命令
├── src/
│   ├── CMakeLists.txt          # QtShadcn 库（qt_add_qml_module, URI: QtShadcn）
│   ├── qml/
│   │   ├── Theme/
│   │   │   ├── QtShadcnTheme.qml    # 声明式主题入口（绑定 C++ ThemeManager）
│   │   │   └── VariantTokens.qml    # variant → token 映射表（新增 variant 在此加项）
│   │   ├── Components/
│   │   │   ├── ShadcnButton.qml     # 按钮（6 variant × 5 size + loading）
│   │   │   ├── ShadcnButtonGroup.qml
│   │   │   ├── ShadcnToggle.qml
│   │   │   ├── ShadcnToggleGroup.qml
│   │   │   ├── ShadcnSpinner.qml
│   │   │   ├── ShadcnCard.qml        # 卡片容器（M3）
│   │   │   ├── ShadcnCardHeader.qml
│   │   │   ├── ShadcnCardTitle.qml
│   │   │   ├── ShadcnCardDescription.qml
│   │   │   ├── ShadcnCardContent.qml
│   │   │   ├── ShadcnCardFooter.qml
│   │   │   ├── ShadcnInput.qml       # 文本输入（M3）
│   │   │   ├── ShadcnBadge.qml       # 徽标 6 variant（M3）
│   │   │   ├── ShadcnSwitch.qml      # 开关（M3）
│   │   │   ├── ShadcnTabsList.qml    # 标签页容器（M3）
│   │   │   ├── ShadcnTabsTrigger.qml
│   │   │   ├── ShadcnTabsContent.qml
│   │   │   ├── ShadcnDialog.qml      # 对话框（M3）
│   │   │   ├── ShadcnDialogContent.qml
│   │   │   ├── ShadcnDialogHeader.qml
│   │   │   ├── ShadcnDialogTitle.qml
│   │   │   ├── ShadcnDialogDescription.qml
│   │   │   └── ShadcnDialogFooter.qml
│   │   └── ...                # Icons / Animations / Utils（M4+）
│   └── core/                  # C++ 能力层
│       ├── thememanager.{h,cpp}     # Theme 引擎（tokens 字典 + mode 切换）
│       ├── iconregistry.{h,cpp}     # SVG 图标注册/加载（M4）
│       └── models/                  # QAbstractListModel 等（M5）
├── examples/
│   └── showcase/              # 组件展示应用（每个里程碑的验证载体）
│       ├── Main.qml           # 左侧菜单 + 右侧内容区（右上角主题色/明暗切换）
│       ├── pages/             # 每个组件一个展示页，新增组件 = 加页 + 菜单加一项
│       │   ├── OverviewPage.qml
│       │   ├── ThemePage.qml
│       │   ├── ButtonPage.qml
│       │   ├── ButtonGroupPage.qml
│       │   ├── TogglePage.qml
│       │   └── SpinnerPage.qml
│       └── main.cpp
└── docs/                      # Docus 文档站（本目录）
    ├── content/               # Markdown 内容
    ├── public/                # 静态资源（logo / favicon）
    └── nuxt.config.ts

QML 模块约定

  • qt_add_qml_module 生成 URI QtShadcn，使用方 import QtShadcn
  • 组件命名带 Shadcn 前缀（避免与 QQC 基类同名冲突），文件放 src/qml/Components/
  • 新增组件需加进 src/CMakeLists.txt 的 QML_FILES
  • 组件内部统一 import QtQuick.Controls.Basic（style-specific import 是 token 自绘的前提，锁定 Basic style）

C++ 能力层（核心原则：QML 管 UI，C++ 管能力）

模块职责里程碑
ThemeManagertoken 字典、mode 切换、主题持久化M1 ✅
IconRegistrysvg 图标注册 + currentColor 替换渲染，image://icons/name?color=... 动态变色M4
ModelsQAbstractListModel 基类，供 Table/Select 数据源M5
WindowManager多窗口/原生窗口能力（可选）M5

如何使用

主题接入与各组件用法示例。

里程碑

组件开发路线图与当前进度。

Copyright © 2026