一套总结自 Qt Creator 源码结构的通用项目管理模板，核心库基于 QtWidgets 构建，并集成了 Ribbon、可停靠窗口（Dock）、自定义窗口（Window）等常用界面组件与第三方类库。
qtcanpool 旨在提供优秀的项目管理方式、多样的选择与优质的控件。
| 组件 | 命名空间 | 说明 |
|---|---|---|
| qxcore | QxCore |
基础设施库：配置（QxSettings）、日志（QxLogger）、语言切换（QxTranslator），仅依赖 Qt Core |
| qxtheme | QxTheme |
主题引擎：调色板 + 样式表统一应用（Office / WPS / Dark）、运行时切换、选择持久化、跟随系统深浅色 |
| qxribbon | QxRibbon |
Ribbon 风格界面组件（菜单栏 / 页 / 分组等） |
| qxdock | QxDock |
可停靠窗口组件（布局管理、浮动容器等） |
| qxwindow | QxWindow |
自定义窗口组件（无边框窗口、系统按钮代理等） |
| qxapp | QxApp |
应用框架库：RibbonAppWindow（无边框 Ribbon 窗口）与 QxAppShell 应用外壳（导航轨 + 页面栈 + 停靠区 + 状态栏 + 启动屏 + 布局持久化）、应用内通知（QxToast）、设置界面（QxPropertyEditor / QxSettingsDialog） |
| qtcompat | — | Qt 5 / Qt 6 跨版本兼容辅助头（header-only） |
qcanpool 已于 3.2 删除。 它在 3.1 已被清空（legacy Ribbon 物理移除、11 个遗留控件下线、 7 个通用控件迁入
qxapp并改名），只剩 7 个带弃用告警的转发头；3.2 连这个库一起消失， 旧名不再存在。迁移见doc/design/3.0-MIGRATION.md。
- 在线文档：https://canpool.github.io/qtcanpool/ —— C++ API 参考（Doxygen）+ 使用指南，由 GitHub Actions 从
master自动发布 - 本地构建文档站点：只需要 Doxygen（和可选的 Graphviz），不需要 Qt，因为文档直接读头文件而非编译
cmake -S doc -B build-docs
cmake --build build-docs --target docs # 产物在 build-docs/html/index.html- 指南源码在
doc/pages（构建、架构、组件、主题、AppShell、迁移），与 API 一同发布
AppShellDemo 已编译为 WebAssembly，可直接在浏览器中打开，无需安装 Qt 或编译器：
- 在线 demo：https://canpool.github.io/qtcanpool/demo/ —— 一个完整的应用外壳：侧边导航、页面切换、可停靠面板、主题切换与布局持久化
| 一级目录 | 二级目录 | 说明 |
|---|---|---|
cmake |
CMake 构建框架 | |
demos |
综合示例程序 | |
doc |
文档：Doxygen 站点源码（Doxyfile.in、pages/ 指南、qtcanpool-doxygen.css）与设计文档 |
|
examples |
控件级示例 | |
projects |
项目示例：template 最小应用模板、consume SDK 消费验证、staticlink 静态链接示例 |
|
scripts |
辅助脚本：new-project 生成新工程骨架、push 推送双远程、project.py 工程工具 |
|
src |
libs |
基础类库 |
modules |
基础模块：实用的代码，但未形成类库规模 | |
plugins |
基础插件 | |
shared |
共享的实用代码 | |
tests |
单元测试（CTest） | |
thirdparty |
第三方库使用案例 |
自 3.0 起的基线：
- Qt 5.15 及以上（主推 Qt 6.5 / 6.8 LTS）
- C++17
- CMake 3.16+（推荐最新版本）
历史测试环境（2.x 时期验证，3.0 不再保证）：
- Qt 6.8.1 / 6.5.3 / 5.15.2 / 5.14.2 / 5.12.12 / 5.11.1（MinGW / MSVC，64bit）
- 其它环境未测试，推荐使用 Qt LTS 版本
CMake 为主要构建方式（qmake 自 3.0 起冻结为只读，后续版本移除）。
# 配置（Qt 通过 CMAKE_PREFIX_PATH 指定）
cmake -S . -B build -DCMAKE_PREFIX_PATH=<Qt安装目录>/<版本>/<编译器> -DCMAKE_BUILD_TYPE=Release
# 编译
cmake --build build --config Release --parallel
# 运行单元测试
ctest --test-dir build -C Release --output-on-failure说明：
- 各功能开关（
WITH_DEMOS、WITH_TESTS、WITH_DOCS等）可通过cmake -S . -B build -LH查看 -DWITH_DOCS=ON会把文档站点目标docs一并加入主构建（只需 Doxygen）；只想要文档时用上面的cmake -S doc -B build-docs- 亦可使用 Qt Creator 直接打开根目录
CMakeLists.txt（或早期兼容的qtcanpool.pro） - 编译出的 demo 位于构建目录的
bin/（Windows）或libexec/qtproject/（其它平台），例如RibbonDemo、DockDemo、AppShellDemo（应用外壳：导航 + 页面 + 停靠 + 主题 + 布局持久化）
安装与下游消费：
# 公开头文件与 CMake 包配置位于 Devel 组件，需显式安装
cmake --install build --config Release --prefix <安装目录>
cmake --install build --config Release --prefix <安装目录> --component Devel下游工程 find_package(QtCanpool) 后可直接链接 QtCanpool::qxcore / QtCanpool::qxribbon / QtCanpool::qxapp 等目标；
仓库内 projects/consume 是最小下游示例，vcpkg / Conan 骨架见 ports/（未经 CI 验证）。
- 格式：
x.y.z（主版本.次版本.补丁版本）
| 分支 | 说明 |
|---|---|
| master | 主线分支 |
| develop | 历史分支，开发已统一到 master |
| release-x.y | 版本分支，用于维护特定发布版本 |
- 版本发布以 tag 标记；若某版本存在需修复的缺陷，将以对应版本分支的形式进行维护
- C++ 风格：Google C++ Style Guide、Qt 编程风格与规范
- 源文件编码：全英文源文件采用 UTF-8；包含中文的采用 UTF-8 with BOM
- 代码中的注释一律使用英文（文档等
.md文件不拘） - 代码格式化：随仓库提供
.clang-format（C++17），CI 中作为强制门禁 - Git 提交格式（自 3.0 起）：
type(scope): subject，以区分早期提交格式- 提交信息一律使用英文（subject 与正文）
type：feat/fix/docs/style/refactor/perf/test/build/ci/chore/revertscope：受影响范围，如qxcore/qxtheme/qxribbon/qxdock/qxwindow/qxapp/project/ci/test/docs- 示例：
feat(qxribbon): add ribbon gallery group、fix(qxwindow): fix taskbar coverage on secondary screen - 早期提交格式参考：git 知：提交格式
- 欢迎提交 issue 对关心的问题发起讨论
- 欢迎 Fork 仓库并通过 pull request 贡献代码
- 贡献者可在文件头版权中添加个人信息，格式如下：
/**
* Copyright (C) YYYY NAME <EMAIL>
* Copyright (C) 2023 maminjie <canpool@163.com>
* SPDX-License-Identifier: MulanPSL-2.0
**/dockdemo
ribbondemo
最新版本效果图：
qxwindow demo
appshell —— 应用外壳示例（导航轨 + 页面栈 + 停靠区 + 状态栏 + 布局持久化），也是 WebAssembly 在线演示的载体（https://canpool.github.io/qtcanpool/demo/），目前只有 CMake 构建：cmake --preset qt6 && cmake --build --preset qt6。
MyCAD
MyCAD 是基于 FreeCAD-1.0.0 源码集成 QxRibbon 组件的作品，旨在实现 FreeCAD 的现代化界面（Ribbon 风格）。
下载源码，使用 Qt Creator 打开 qtcanpool.pro，右击 ribbondemo 或 dockdemo 并选择 Run 即可体验：
本仓库未来将只维护核心库，其它库将以独立的 qtcanpool-LIBNAME 仓库维护，可通过 qtcanpool 标签检索：
如果您觉得本项目对您有帮助，欢迎赞助，助力项目更好地发展。
赞助名单：名单
- QQ 群：831617934（Qt 业余交流）
- 本项目遵循 MulanPSL-2.0 开源许可协议
- 集成组件遵循各自的开源许可协议