简介：面向Qt/C++开发者的自定义控件练习包，收录十套精美控件示例，涵盖滑块条、圆形组件、水波纹进度条、范围选择滑块、开关按钮、刻度尺滑块、样式化组件等常见界面元素。每个控件均通过继承QSlider、QProgressBar、QPushButton等基类，重写paintEvent绘制个性化外观，并利用QPainter绘图、QPropertyAnimation动画和QSS样式表实现状态反馈与过渡效果，例如水波纹进度条借助定时器与路径填充模拟动态画面，范围选择滑块需要约束双滑块边界。这些示例适合初学者逐行理解事件处理和自定义绘制流程，也可供中级开发者迁移到仪表盘、设置面板、播放器等项目中复用，还可应用于自绘界面、皮肤定制、工业控制面板等场景。压缩包共178个文件，包含48个cpp、35个h源文件，以及11个ui界面、10个pro工程配置、qrc资源与ttf字体文件，整体仅1.19MB，按模块划分清晰，便于独立阅读和裁剪。已有1180人学习下载，源码附带完整工程与makefile，可直接编译运行验证效果，帮助掌握Qt图形视图模型、信号槽通信和组件封装技巧。
1. 为什么项目一到自绘这块，就得靠这些控件源码
做Qt开发的人迟早会遇到一个尴尬时刻：视觉稿里明明画得挺好看，用QSS调了半天，原生控件换皮换到极限，还是出不来效果——比如一个带刻度、带指针、带实时数据的仪表盘，或者一个按压时能反馈真实手感的开关按钮。QSS能做圆角、渐变、阴影这些外观，但控件的交互行为、动态绘制、数据绑定，它一概管不了。这个时候就必须走自定义控件的路子，而手写一套能打的控件，从坐标计算到重绘优化，没有三五天根本下不来。
所以我一直觉得，像“Qt自定义控件十套demo源码”这类打包资源，价值不在那几份源码本身，而在于它替你趟平了“自绘控件”这条路上最容易摔跤的几段路。我现在做项目，凡是遇到特殊控件需求，第一反应不是从零写，而是先翻手头的demo库，看有没有形态接近的，改、扩、拆，远远比自己凭空造快得多。
这套源码适合谁？三类人最值回票价：一是刚入门Qt没多久、想搞明白QPainter怎么用的新手，demo里能看到一整套完整控件的绘制流程，比看文档零散知识点高效得多；二是正在做组态、仪表、监控类项目的开发者，热词里“qt 做组态”“qt 加载焊缝”这类需求，底层都要靠自绘控件支撑；三是准备面试时想拿几个能讲的亮点项目的同学。下面我从实际拆读源码的角度，把这套demo里最值得关注的绘制思路、常见坑位和改造方法逐一拆开讲，按我自己的实战经验来。
2. 十套demo里最有含金量的五个绘制思路
源码包里通常不会只有一种类型的控件，最常见的组合是：仪表盘、滑动开关、自定义进度条、实时曲线/频谱、消息气泡或者提示框，再配几个带交互效果的按钮或者面板。我不会一个个平铺，那样反而没有参考价值。真正要学的是它们背后反复出现的绘制模式，掌握这几种模式，十套demo就能当成一百套来用。
2.1 仪表盘的刻度坐标转换：从角度到点的换算逻辑
仪表盘是自绘控件里最经典的一类，几乎每个做工业项目的人都要碰。它的核心逻辑只有一句话：把一个扇形角度区间，映射成画布上的点坐标。具体来说，控件先定一个起始角度和跨角度，比如从135度开始、跨越270度，然后根据数值大小，在线性映射得到一个当前角度，再用三角函数算出指针终点坐标。
// 角度转坐标：x = centerX + radius * cos(rad), y = centerY + radius * sin(rad) qreal rad = (angle - 90) * M_PI / 180.0; // 减90度因为Qt坐标系的0度在三点钟方向 qreal x = m_center.x() + m_radius * cos(rad); qreal y = m_center.y() + m_radius * sin(rad);这段代码看着简单，但很多新手第一次写都会栽在“仪表盘的零刻度到底在哪个位置”这个问题上。Qt的绘图坐标系以正右方为0度，顺时针为正方向，而仪表盘习惯上把0点放在正上方或者左下方，所以要做一次坐标系的偏移换算。demo里通常会封装一个updateAngle()函数，把所有角度计算集中在一处，这个习惯很值得学——坐标换算的代码一旦散落在paintEvent各处，后面要调表盘范围会改到怀疑人生。
2.2 滑动开关的动画：QPropertyAnimation与属性插值
第二类值得拆的是带动画的开关控件。热词里虽然没直接提“开关”二字，但“qt好看的等待提示框”“qt模拟鼠标点击事件”这类搜索背后，其实都是同一个需求：控件要有反馈，要动起来。滑动开关的难点不在画一个圆角矩形，而在滑块从左边滑到右边这个过程，如何跟用户点击的状态同步。
实现思路通常是用QPropertyAnimation对“滑块x坐标”这个属性做渐变。定义控件里有一个m_offsetX，paintEvent里画滑块时直接取这个值，点击时启动动画从0插值到滑块滑轨宽度减去滑块宽度。这种方式的好处是动画框架帮你处理帧刷新，不用自己开定时器反反复复update。
m_anim->stop(); m_anim->setDuration(150); m_anim->setStartValue(m_offsetX); m_anim->setEndValue(m_checked ? maxOffset : 0); m_anim->start();要提醒的是：动画时长别设太长，150毫秒左右是手指按压反馈最舒服的区间，超过250毫秒就会觉得拖沓。另外别忘了在属性值变化时调用update()让控件重绘，这个是由QPropertyAnimation内部通过属性写函数触发的，所以setter里一定要emit或主动update，不然控件会“卡住不动”。
2.3 实时曲线的双缓冲设计：数据写入与绘制分离
实时曲线或者频谱图，是十套demo里“技术含量”最高的一类，因为涉及性能和线程。热词列表里“qt 频谱图”“qt 绘制三维曲线”“qchart实现图片缩放”这些，全都指向这类需求。
实时曲线的经典做法是：控件内部维护一个定长的环形缓冲区（QVector或者QCircularBuffer），外部数据往缓冲区写，paintEvent读取缓冲区并绘制。写数据和绘制必须走不同的路径，不能在paintEvent里直接接收外部数据，也不能在数据写入的线程里直接调用update。Qt的跨线程刷新标准姿势是信号槽连接，带队列连接时槽函数会在主线程执行，这样update()始终在主线程被调用。
// 数据写入端（可能是子线程） emit newDataArrived(value); // 控件内部，主线程 void WaveWidget::onNewData(qreal v) { m_buffer.append(v); update(); // 只允许主线程调用 }绘制曲线本身不复杂，就是拿QPainterPath把数据点连起来，但要注意两个优化点。第一，如果数据点很多，没必要每帧把所有点都重画，可以只在末尾追加一小段路径，旧路径缓存成QPixmap；第二，坐标变换用painter的scale/translate，不要自己在数据层做缩放，这样代码更清晰。
2.4 自定义样式的消息气泡与等待框：窗口透明与无边框
“好看的等待提示框”这类控件，市面上能找到的demo大多是继承QWidget，去掉窗口边框之后自己画一个半透明圆角矩形，内部放一个动态旋转的圆弧或者几个跳动的圆点。其中最容易踩坑的是透明窗口的配置。要让窗口背景真正透明，必须设置：
setAttribute(Qt::WA_TranslucentBackground); setWindowFlags(Qt::FramelessWindowHint | Qt::Dialog);这两行缺一不可。只去掉边框不设置TranslucentBackground，背景会变成一块黑的黑底；只设置透明不去边框，边框阴影又很难看。demo源码里这一类控件通常还封装了“模态阻塞”的逻辑，通过一个局部事件循环或者exec()实现等待期间不响应主窗口操作。如果需要更轻量的方式，可以改用QProgressDialog配合自定义绘制，但灵活性会差一些。
2.5 手势密码与可拖拽控件：事件系统的完整链路
很多外包项目会要手势解锁，它本质上是一套完整的鼠标事件链路：mousePressEvent记录起始格、mouseMoveEvent实时更新连线、mouseReleaseEvent判断结果并启动清除动画。热词里“qt模拟鼠标点击事件”“qt桌面画线”刚好对应这个场景。
这里想多提一句：自定义控件的事件处理，最重要的习惯是保留对父类事件的调用。重写mousePressEvent时忘了调用QWidget::mousePressEvent(e)，会导致父控件的快捷键、聚焦逻辑统统失效，表现就是“界面好像变迟钝了”。demo里基本不会犯这种错，但它们通常也不会刻意讲，这是我建议你读源码时逐行关注的一个细节。
3. 跑通源码时容易栽的坑，我按踩过的顺序说
下载源码包、解压、用QtCreator打开——这一步本身就能拦下一批人。尤其是“qt自定义控件qtcreator和qtdesigner版本不一样”这类问题，搜索量一直居高不下，说明配置兼容是个普遍痛点。我把自己跑demo时踩过的坑按排查先后顺序列一遍，你照着检查能省半天时间。
3.1 Qt版本与编译套件的匹配问题
用QtCreator打开pro文件时，第一件事是确认套件（Kit）里选择的Qt版本和编译器能对上。很多demo源码是在Qt 5.12或Qt 5.15下写的，如果你的机器装的是Qt 6.x，可能遇到QRegExp被移除、或者某种写法在新版本里不再被支持的情况。遇到编译报错，不要马上怀疑源码有问题，先用小范围注释法定位。
具体操作是：在pro文件里看到类似greaterThan(QT_MAJOR_VERSION, 5)的条件判断，说明作者已经考虑过版本差异；如果没看到，你就要自己留意Qt 5独有的API。解决思路有两种：一是给项目创建一个独立的Kit，专门用Qt 5.15.2编译；二是手动把废弃API换成新写法，比如QRegExp换QRegularExpression。对于只是跑demo验证效果的人来说，第一种更省事。
3.2 运行时提示“找不到Qt平台插件”这类环境问题
Linux上最容易出现could not find the qt platform plugin "wayland"或者qxcConnection failed to initialize xrandr这类型错误。前者是Qt运行库没有正确加载wayland平台插件，后者经常出现在没有图形显示环境、或者SSH连接远程开发板的情况下。解决办法通常是安装对应的Qt平台插件，或者在运行时指定：
export QT_QPA_PLATFORM=offscreen # 无界面环境跑测试时 export QT_QPA_PLATFORM=xcb # 正常X11环境 export QT_QPA_PLATFORM=wayland # Wayland会话环境如果你已经安装了xcb插件仍然报错，再检查一下系统依赖库是否齐全，比如libxcb-*系列。这个坑在打包发布到其他机器时更常见，热词里“qt发布软件”“qt崩溃”背后的原因很大比例就是平台插件缺失。
3.3 高分屏下的模糊与坐标偏移问题
如果运行环境是一台高分屏Windows机器，不做缩放适配的话，控件边界会出现严重的模糊感。这里的关键是理解设备像素比devicePixelRatio。Qt默认在高分屏上会把逻辑坐标映射到物理像素，但如果你在paintEvent里用了不正确的坐标变换，就会导致绘制结果发虚。
最佳实践是在窗口创建后设置：
QApplication::setAttribute(Qt::AA_EnableHighDpiScaling);然后QPixmap或者QPainter绘制时，按实际设备像素比调整坐标。源码里如果没做这一步，你在高分屏上看到的demo就会明显比设计稿“肉”一圈。这也是自绘控件从demo走向产品时最先暴露的问题。
3.4 QtCreator打开ui文件样式异常：Designer版本不一致
“qt自定义控件qtcreator和qtdesigner版本不一样”这个问题，本质是项目中ui_xxx.h文件是由某个版本的uic生成的，而当前QtCreator自带的Designer版本较新或较旧，导致打开窗体文件时控件属性映射错位。多数时候不是代码逻辑错误，而是元信息不一致。
最简单的规避方法：不要手动编辑ui文件，在QtCreator里右键ui文件选择“打开方式”为Qt Designer，让IDE自己完成版本转换。如果源码包里的ui文件比较老，升级打开后可另存为新版本格式，再重新构建项目。另外，自绘控件如果做成设计器插件，必须确保插件是用与当前Designer完全相同的Qt版本编译的，否则插件加载不出来——这也是“qtdesigner里看不到自定义控件”的常见原因。
3.5 paintEvent里做耗时操作导致的界面假死
有些demo的作者为了追求“动态效果好”，会在paintEvent里动态申请大块QPainterPath，或者频繁调用QFontMetrics计算文本宽度。数据量小的时候没问题，一旦数据量上来，重绘一次就要几毫秒甚至几十毫秒，界面拖动时明显卡顿。
我的原则很简单：paintEvent里只做绘制，不做算法计算。如果一次重绘需要大量计算，提前在数据更新函数里算好，或者把计算结果缓存到成员变量。另一个相关技巧是save/restore配对。每次paintEvent开头调painter.save()，结尾调painter.restore()，避免状态污染。很多调试了一天最后发现是绘制状态没复位的问题，根源就在这两行没写。
4. 把demo里的控件改造成项目可用控件的四级跳
源码包里的demo本质上是教学性质，离“项目可用”还有一段距离。我把改造拆成四个层级，每一级对应一类实际项目里一定会遇到的需求。
4.1 用Q_PROPERTY把写死的参数开放出来
第一件事，把控件里写死的颜色、大小、范围改成属性。demo为了演示方便，经常把变量直接写在private里，但你接手项目后，不可能每次都改源码来适配不同界面。正确做法是定义Q_PROPERTY，让参数可以在Qt Designer的属性栏里直接调，或者通过setter动态修改。
Q_PROPERTY(QColor arcColor READ arcColor WRITE setArcColor NOTIFY arcColorChanged)这一步还有个额外好处：配合Q_PROPERTY的NOTIFY信号，可以直接绑定到QML或者动画框架里，实现“属性变化时自动重绘”。这比手动调用update()优雅得多，也让控件能无缝接入类似QSS的动态属性选择器。
4.2 让控件支持样式表和QStyleOption
很多自绘控件的一个隐藏问题是：设置stylesheet不生效。原因在于，自绘控件直接忽略QStyleOption，全部走自己的paintEvent，样式表自然就切不进来。要支持QSS，正确的做法是先调QStyleOption opt; opt.initFrom(this);，再在绘制时尊重样式表给定的背景和状态。
一个标准的可换肤控件，paintEvent开头通常是：
QStyleOption opt; opt.initFrom(this); style()->drawPrimitive(QStyle::PE_Widget, &opt, &painter, this);这段代码的意义是让Qt先绘制样式表指定的背景，之后你再叠加自绘内容。这样用户可以通过QSS改控件的背景色，而自绘的装饰层保持不变。这招在做“换肤功能”时极其好用，十套demo里如果哪套做到了这种程度，你就把它的写法抄到自己项目里。
4.3 数据接口对齐原生控件习惯
项目里的控件使用者，最怕的是“每个控件都有一套自己定义接口”。好的自定义控件，setValue、setRange、setText、clear这些方法名应该和原生QProgressBar、QSlider保持一致。这个看似无关紧要，但能显著降低团队使用成本。我在改造demo时，会先写一个接口清单，根据控件功能，对齐原生控件的命名习惯；比如仪表盘就模仿QProgressBar提供setRange、setValue、valueChanged信号，这样接入数据绑定时，老成员不用看文档也能猜个大概。
4.4 子线程更新的信号槽封装
项目里真正跑起来之后，数据基本都来自子线程。demo里的控件大多是主线程直接setValue，不涉及线程问题。改造时必须明确：自定义控件里凡是和UI刷新相关的操作，一律通过信号槽转到主线程。不要试图在子线程里直接调用控件的public方法修改状态，轻则界面错乱，重则崩溃。
通常会做一个独立的数据源类，对外暴露appendData()接口，内部识别线程并emit队列信号，让控件槽函数在主线程执行。这个模式也符合热词里“qt多线程”“qcoreapplication::exec()之后就无法捕获了”所反映的普遍困惑，很多崩在子线程的bug都是这个原因，所以这段一定要当成重头戏来改。
5. 这套源码还能怎样拓展出更多玩法
十套demo读透之后，它能发挥的价值就不仅仅是“照着跑一下”这么简单了。我分享几个我实际操作中验证过、比较值得投入的扩展方向。
5.1 把控件库编译成独立的插件库
当积累的自定义控件超过5个，就应该考虑做成独立的控件库，而不是每次复制源码进项目。用Qt的插件机制可以写一个接口类，把控件注册进Qt Designer，这样团队里所有项目都能直接拖拽使用，也避免了每个项目维护一份控件代码的重复劳动。
这里提个具体步骤：建一个独立的子目录工程，写成Qt Plugin，其中关键是导出接口：
class CustomWidgetsPlugin : public QObject, public QDesignerCustomWidgetInterface { Q_OBJECT Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface") Q_INTERFACES(QDesignerCustomWidgetInterface) };编译完成后把插件dll放到Qt的plugins/designer目录下，Designer里就能看到自定义控件。这一步做完，项目的控件复用率会有一个质的提升。
5.2 把控件移植到QML方向
如果你的项目开始往QML迁移，那么这套demo同样可以作为绘制逻辑参考。QML里的Canvas、Shape元素能复刻相当大的自绘控件功能，只不过把C++的paintEvent换成了JS绘制的onPaint，把QPropertyAnimation换成了Behavior或者Animation组件。难点在于坐标系和状态管理，绘制思路本身是一致的。热词里“qt自定义控件”的搜索量持续走高，恰恰说明这个方向需求量很大。
5.3 结合QChart、OpenGL做复杂场景控件
最后还能把demo里的绘制技巧跟Qt生态里的专业模块结合。比如热词里“qchart实现图片缩放”“qt绘制三维曲线”，明显是有人想在图表里叠加自定义标记、自定义游标或画刷。这时候，你在demo里学到的坐标变换、事件链路和刷新策略就派上用场了——QChart本身支持自定义item和图元，完全可以嵌入一个自绘控件作为覆盖层。
我在实际项目里做过一个焊缝加载与提取界面的预览控件，底层就是自绘的缩放背景加上QChart的曲线层，再用鼠标事件模拟平移缩放，这套结构就是从一节demo里拆出来改的。所以说，把十套demo理解为十个积木块，比把它们理解成十个做好的模型，价值要大得多。
最后再分享一个小技巧：每次写完一个自绘控件，把它压成一个零依赖的单文件，命名加上日期和版本号，攒久了就是你自己的控件库。不要等到需要用的时候才去翻别人发的zip包——那些包能帮你入门，但真正能帮你扛项目的，永远是自己积累下来、踩过坑修过bug的那份源码。
本文还有配套的精品资源，点击获取
