嘿！这里是Awesome Embedded Studio！我相信大家第一次接触 Qt 的时候，对着 QObject::connect 的四个参数发呆了整整一下午。后来又因为忘记加 Q_OBJECT 宏，收获了一个莫名其妙的 vtable 错误。再后来，在信号槽的跨线程调用上翻车，在对象树的内存管理上踩雷，在 MOC 生成的代码里迷失方向……
笔者就是这样过来的——有时候博客不靠谱，对着Qt5看着Qt6代码抓耳挠腮，想理解底层原理发现要不然过时了，要不然看不懂。所以——这是一份会陪着你走完整条路的教程——从第一个 QApplication 到读懂 MOC 生成的那一刻。我们会吐槽，会叹气，会一起熬夜调试，但你绝对不会断层。
希望这里的内容能让你Happy Qt Coding!
AwesomeQt 是一份面向 C++ 开发者的 Qt 6 全栈教程，采用三层分级结构：
入门层 → 能跑起来，理解核心概念，初步使用 API
进阶层 → 掌握高级用法，写出工程级代码
专家层 → 读懂 Qt 源码，理解设计模式与实现原理
本项目隶属于组织 Awesome-Embedded-Learning-Studio 的文档教程
| 你需要... | 版本要求 |
|---|---|
| C++ 基础 | 熟悉类、继承、指针、模板 |
| CMake | ≥ 3.26 |
| 编译器 | MSVC 2019/2022 / MinGW 11.2+ / GCC 11+ |
| 操作系统 | Windows 10/11 / Linux / WSL2 |
# 1. 克隆仓库
git clone https://github.com/Awesome-Embedded-Learning-Studio/Tutorial_AwesomeQt.git
cd Tutorial_AwesomeQt
# 2. 阅读教程索引
# 打开 tutorial/index.md 选择你的起点
# 3. 从环境搭建开始
# tutorial/beginner/00-environment-setup/如果你是零基础，建议按顺序从「环境搭建」开始。如果你已经有 Qt 经验，可以直接跳到感兴趣的模块。
入门层 ██████████ 134 / 134 篇（代码示例） · 137 篇教程文章
进阶层 ░░░░░░░░░░ 0 / 137 篇
专家层 ░░░░░░░░░░ 0 / 142 篇
🚀🚀🚀 更加详细的进度：tutorial/index.md
见 changelogs/ 目录。
环境搭建 → QtBase → QtGui → QtWidgets → 项目实战 → QtNetwork → 扩展模块 → QML
适合：从没接触过 Qt，想系统学习的开发者。
环境搭建（重点 CMake）→ Qt 6 新变化 → 直接跳到感兴趣的模块
适合：有 Qt 5 经验，想快速迁移到 Qt 6 的开发者。
完成入门层 → 专家层源码解析章节（MOC 原理、信号槽底层、事件循环...）
适合：想理解 Qt 底层实现的设计模式爱好者。
文档里不会列出所有函数签名，那些东西官方文档写得更好。我们讲的是：什么时候用什么、为什么这样用、哪里会踩坑。
每个知识点至少三个真实踩过的坑：
> ⚠️ 坑 #N：[坑的名字]
> ❌ 错误做法：[描述或伪代码]
> ✅ 正确做法：[描述或伪代码]
> 💥 后果：[这样写会崩溃 / 内存泄漏 / 信号永远不触发...]
> 💡 一句话记住：[总结]穿插在讲解中的互动题目，不只是读完就算：
- 📝 口述回答：用自己的话说说概念
- 🔲 代码填空：补全关键代码
- 🐛 调试挑战：找出有 bug 的代码
- 📖 源码阅读题（专家层）
每篇配套一个动手项目，不做永远学不会。
每篇末尾附上官方文档链接，全部经过验证可达。遇到疑问，官方文档是最终权威。
项目包含一套可复用的自定义控件库，位于 widget/ 目录。每个控件都是独立的、可编译的库组件，统一使用 AwesomeQt:: 命名空间。
当前已实现：
| 控件 | 说明 |
|---|---|
StatusLED |
状态指示灯，支持 4 种状态（Normal/Warning/Error/Offline）+ 闪烁动画 |
构建系统： cmake/AwesomeQtWidgets.cmake 提供了 awesomeqt_add_widget() 等函数，支持 INDIVIDUAL（每个控件独立 .so）和 MERGED（合并为单一库）两种构建模式。
除了教程和控件库之外，项目还规划了完整的代码实例库。详见 todo/catalogs/ 目录下的规划清单：
| 清单 | 内容 | 条目数 |
|---|---|---|
todo/catalogs/01-widget.md |
单个自定义控件（按钮/标签/输入/进度条/仪表盘/图表/表格/树/列表等，22 个分类） | 500+ |
todo/catalogs/02-app.md |
完整应用 Demo（开发工具/网络工具/文件工具/系统工具/图像工具/多媒体/办公/游戏等） | 200+ |
todo/catalogs/03-model.md |
控件组合与设计模式（窗口框架/导航布局/主题系统/表单/属性编辑器/拖拽/命令模式等） | 300+ |
todo/catalogs/04-qml.md |
QML 专项项目 | 100+ |
todo/catalogs/05-industrial.md |
工业级项目模板（HMI 仪表盘/SCADA 监控/车载中控等） | 规划中 |
代码实例统一使用 Qt 6 + CMake 构建，第三方依赖通过 CMake FetchContent 自动管理。
本项目的代码实例规划大量参考了以下开源项目和社区资源，在此致以诚挚的感谢：
| 项目 | 作者 | 说明 |
|---|---|---|
| QWidgetDemo | feiyangqingyun (Qt实战) | 5800+ Stars，涵盖 100+ 个 Qt 自定义控件、工具和界面 Demo，是本项目最核心的参考来源 |
| MyTestCode | gongjianbo1992 | 丰富的 Qt/QML 博客示例代码，涵盖网络、多线程、OpenGL、插件、QML/C++ 互操作等 |
| TTKWidgetTools | Greedysky Studio | 86 个精美自定义控件，包含按钮、标签、进度条、仪表盘、滑块等，支持 Qt 4/5/6 全版本 |
| 项目 | 说明 |
|---|---|
| Qt-Advanced-Docking-System | 高级停靠窗口框架，IDE 风格 Dock 管理器 |
| qt-material-widgets | Material Design 风格的 Qt Widgets 控件库 |
| Qt-ShowyWidgets | 花式/创意 Qt 控件集（心形开关、线条开关等） |
| QCodeEditor | Qt 代码编辑器控件（行号、语法高亮、代码折叠） |
| JKQTPlotter | 功能丰富的 Qt 2D 绘图库 |
| Chart-Qt | 高性能 Qt 图表库 |
| QDoubleRangeSlider | 双端范围滑块控件 |
| Qt-FacileMenu | 动画右键菜单控件 |
| QGeoView | Qt 地图数据可视化控件 |
| prison (QR/DataMatrix) | Qt 条形码与二维码生成库 |
| SARibbon | Microsoft Office 风格 Ribbon 工具栏控件 |
| KDDockWidgets | KDAB 出品的停靠窗口框架 |
| QLineEditExt | 混合型输入控件（滑块+文本+进度条） |
| QWidget-FancyUI | Qt6 现代化 UI 组件库 |
| QCustomPlot | 高质量 2D 绘图控件 |
| Qwt | 科学与技术绘图库 |
如果您是以上项目的作者，且对本项目的引用方式有任何疑问或希望调整，欢迎通过 Issue 联系我们。
| 项目 | 说明 |
|---|---|
| Qt 版本 | 6.9.1（编写时的 LTS） |
| 构建系统 | CMake 3.26+ |
| C++ 标准 | C++17/20 |
| 测试平台 | Windows 10/11, Ubuntu 22.04+, WSL2 |
| 编译器 | MSVC 2019/2022, MinGW 11.2+, GCC 11+ |
这个教程是动态生成的，持续更新中。
如果你发现：
- 错误或不准确的内容
- 链接失效
- 可以改进的表达方式
- 想要补充的知识点
欢迎提交 Issue 或 Pull Request。
- 作者：CharlieChen
- 邮箱：725610365@qq.com
- 组织：Awesome-Embedded-Learning-Studio
现在你已经知道这是什么了，准备好了吗？从 教程索引 开始你的 Qt 之旅吧！