一套总结自 Qt Creator 源码结构的 Qt Widgets 项目管理模板与组件库。
QtCanpool 提供一整套可直接用于产品开发的界面基础设施：Ribbon 功能区、可停靠窗口、无边框自定义窗口、 应用外壳、主题引擎，以及配置与日志这类应用层必备设施。它的目标是让一个 Qt 桌面项目**第一天就具备** 成熟产品的骨架 —— 统一的项目组织方式、一致的构建与测试流程、开箱可用的界面组件。
为什么是 QtCanpool
| 关注点 | QtCanpool 的做法 |
|---|---|
| 项目组织 | 一套 CMake 框架管理多个项目：库、示例、插件、测试各有约定俗成的落点，新增模块只需一行 add_subdirectory |
| 构建与质量 | CMake 是唯一构建方式（qmake 已于 4.0 移除）；clang-format 作为 CI 强制门禁；CTest 单元测试矩阵覆盖 Qt 5.15 与 Qt 6 |
| 界面组件 | Ribbon、Dock、无边框窗口三类现代桌面界面范式，均可在 Qt 5 与 Qt 6 上编译 |
| 应用骨架 | QxApp::QxAppShell 把导航轨、页面栈、停靠区、状态栏与启动屏组装成一个可直接继承的窗口 |
| 布局与工作区 | saveLayout() 记下窗口几何与停靠布局；QxApp::QxWorkspaceManager 在此之上给排列起名字，可存多套并随时切换（3.3） |
| 主题 | QxTheme::QxThemeManager 统一应用调色板与样式表，支持运行时切换、选择持久化与跟随系统深浅色 |
| 基础设施 | QxCore::QxSettings 负责配置与版本迁移，QxCore::QxLogger 负责带轮转的日志，QxCore::QxTranslator 负责语言切换 |
| 开箱即用 | 生成的工程（见 scripts/new-project）已接好切语言、QxApp::QxToast 应用内通知与 QxApp::QxSettingsDialog 设置界面 |
组件总览
每个组件是一个独立的库、独立的命名空间，可以按需取用。完整说明见 组件全览。
| 组件 | 命名空间 | 说明 | 依赖 |
|---|---|---|---|
qxcore | QxCore | 基础设施：配置（QxSettings）、日志（QxLogger）、语言切换（QxTranslator） | Qt Core |
qxtheme | QxTheme | 主题引擎：调色板 + 样式表统一应用、运行时切换、持久化、跟随系统 | qxcore、Qt Widgets |
qxwindow | QxWindow | 自定义窗口：无边框窗口、系统按钮代理、原生窗口上下文 | Qt Gui |
qxribbon | QxRibbon | Ribbon 风格界面：菜单栏 / 页 / 分组 / 快捷工具栏 | qxwindow、Qt Widgets |
qxdock | QxDock | 可停靠窗口：布局管理、标签化面板、浮动容器 | Qt Widgets |
qxapp | QxApp | 应用框架：RibbonAppWindow、QxAppShell、QxNavigationBar、QxSplashScreen、应用内通知（QxToast）、设置界面（QxPropertyEditor / QxSettingsDialog） | qxribbon、qxdock、qxtheme、qxcore |
qtcompat | — | Qt 5 / Qt 6 跨版本兼容辅助头（header-only） | Qt Core |
**注意**：
qcanpool已于 **3.2 删除**。它在 3.1 已被清空（legacy Ribbon 系列物理移除、 11 个遗留控件下线、7 个通用控件迁入qxapp并改名），只剩 7 个带弃用告警的转发头； 3.2 连这个库一起消失，**旧名不再存在**。详见 迁移指南。
版本对照
**项目版本**（tag 打在它上面）是发布列车号；**每个库另有自己的版本号**，两者互不绑定（K11）。 每次项目发版**结算一次**：这一批里**动了 API 的库才前进号**，没动的库保持原号。所以 3.0 → 3.3 项目版本走了四位，而 qxtheme / qxribbon / qxdock / qxwindow 一位未动——这不是遗漏， 是在声明「这些库本期没有接口变化」。推进规则的完整约定（含发布时的操作步骤）见 doc/ROADMAP-3.x.md 附录 B。
| 项目版本 | qxcore | qxtheme | qxwindow | qxribbon | qxdock | qxapp |
|---|---|---|---|---|---|---|
| 3.0.0 | 0.1.0 | 0.1.0 | 0.1.2 | 0.10.1 | 0.2.0 | 0.0.1 |
| 3.1.0 | 0.1.0 | 0.1.0 | 0.1.2 | 0.10.1 | 0.2.0 | 0.0.1 |
| 3.2.0 | 0.1.0 | 0.1.0 | 0.1.2 | 0.10.1 | 0.2.0 | 0.0.1 |
| 3.3.0 | 0.1.0 | 0.1.0 | 0.1.2 | 0.10.1 | 0.2.0 | 0.0.1 |
（qcanpool 有自己的一套号，且已于 3.2 整库删除，不再列入。）
四行里库号全未动，但内容一直在长：qxcore 多了 QxCore::QxTranslator，`qxapp` 多了 QxApp::QxToast / QxApp::QxToastManager / QxApp::QxPropertyEditor / QxApp::QxSettingsDialog / QxApp::QxWorkspaceManager。这些内容按上面的规则会在 **下一批发布**时结进号里（qxapp 0.0.1 → 0.1.0、qxcore 0.1.0 → 0.1.1），而不是回头改写这里。
快速开始
编译产物中的示例程序位于 bin/，例如 RibbonDemo、DockDemo、AppShellDemo。 完整的构建说明与开关列表见 构建与安装。
在线体验
AppShellDemo 已编译为 WebAssembly，可直接在浏览器中打开，无需安装 Qt 或编译器：
https://canpool.github.io/qtcanpool/demo/
它展示了一个完整的应用外壳：侧边导航、页面切换、可停靠面板、主题切换与布局持久化，全部运行在 QxAppShell 之上。
文档导览
| 页面 | 内容 |
|---|---|
| 构建与安装 | 环境要求、CMake 构建、开关、测试与文档站点构建 |
| 架构与约定 | 库分层、命名空间与 d-pointer 约定、CMake API、编码规范 |
| 组件全览 | 各组件的能力范围、主要类与最小用法 |
| 主题引擎 | 主题引擎：内置主题、运行时切换、跟随系统、自定义主题 |
| 应用外壳 | 应用外壳：页面、停靠区、状态栏、布局持久化、启动屏 |
| 迁移指南 | 2.x → 3.0 / 3.1 迁移：命名空间、类与方法对照、构建迁移 |
环境要求
| 项目 | 要求 |
|---|---|
| Qt | **5.15 及以上**（主推 Qt 6.5 / 6.8 LTS） |
| C++ | C++17 |
| CMake | 3.16 及以上（推荐使用最新版本） |
| 编译器 | 随 Qt 分发的 MinGW；MSVC 2019+；GCC 9+；Apple Clang |
| Doxygen（可选） | 1.9 及以上，仅构建文档站点时需要 |
仓库与许可
- GitHub：https://github.com/canpool/qtcanpool
- Gitee：https://gitee.com/icanpool/qtcanpool
- 使用教程：https://blog.csdn.net/canpool/category_10631139.html
- 许可：MulanPSL-2.0（集成组件遵循各自许可，见
LICENSE.NOTES.md）
