很多人在学Qt的时候，都有个误区：喜欢自己东拼西凑找项目练手，结果连Qt自带的那座“金山”都没发现。如果你装了Qt 5.14.2，打开安装目录下的Examples，找到2D Painting这个示例，花一个晚上把它彻底吃透，你对QPainter绘图体系的理解会直接超过大半靠抄博客学Qt的人。这个示例不算大，但信息密度极高——它把QPainter平时最常用的画线、图形、渐变、路径、图像合成这些能力全部塞进了几个可独立运行的小工程里。这篇文章我就以这个示例为蓝本，把我逐行读代码、改参数、调效果的过程完整拆给你看，包括那些文档里不会明说、但实操一定会踩的坑。
1. 这个示例到底在讲什么，为什么值得逐行读
1.1 先从目录结构看Qt绘图示例的设计思路
2D Painting不是一个单一的main.cpp文件，而是由四个独立子工程组成的示例集合，你可以在 Qt 安装目录的 Examples/Qt-5.14.2/painting/2dpainting 下找到它们。这四个子工程分别是 basicdrawing、gradient、composition、painterpaths。别小看这目录划分，它其实暗合了QPainter体系的核心能力分布：基础图元、渐变填充、图像合成、复杂路径。
我刚开始看这个例子的时候，觉得它无非就是画几个矩形、画几条线。但把每个子工程的代码逐行读完才发现，它真正要教的不是怎么调用函数，而是怎么理解QPainter的状态机制。比如说，几乎所有绘制操作都要在paintEvent里做，为什么？因为系统窗口大小变化、遮挡恢复、调用update()都会触发重绘，QPainter做的事就是把每个重绘周期内的绘制指令全部提交到绘图设备上。只要你的逻辑依赖外部状态，就必须手工管理状态与重绘的关系。这个理解不到位，后面做复杂界面时到处都是毛病。
1.2 什么人适合从2D Painting入手
如果你已经会写简单的Qt窗口程序，但对绘图还停留在“照着网上代码抄个画板”的阶段，这个示例就是为你准备的。它默认你有基本的C++功底、知道类和对象的概念，但不需要你提前懂QPainter的坐标变换、渐变算法、合成模式这些深水区内容。看完之后，你能独立完成自定义控件的绘制、实现图片局部缓存合成、甚至给图表类控件加上抗锯齿渲染。对于刚接触Qt自绘界面的新人，这是性价比极高的一课。
反过来，如果你是老手但一直没有完整读过官方示例，我也建议你回头看看。因为Qt官方示例的代码风格极其克制，几乎每一行都在示范最佳实践。比如它不会在paintEvent里做耗时的数据计算，不会在事件循环里反复创建画笔，不会用魔数写死坐标——这些习惯对于长期维护项目的人来说，比任何“花哨技巧”都重要。
1.3 运行示例前先准备好探索环境
在开始改代码之前，建议你把这四个子工程分别用Qt Creator打开跑一遍。跑的时候留意三个东西：
- 窗口标题，它直接告诉你在显示哪个演示。
- 绘制区域的刷新表现，比如缩放窗口时图形是否出现闪烁、是否出现撕裂感。
- 各个演示页切换时，有没有明显的交互差异。
我这个习惯是从调试嵌入式界面时养成的。很多问题不是代码写错，而是渲染行为不符合预期。你只有在基线环境里先“感觉正常”，后面改参数时才分得清是代码问题还是环境问题。比如经典的半透明重影问题，在有些机器上会因为合成器行为不同而表现不一致。先有基线，再谈排查。
2. QPainter绘图系统的底层逻辑，以及示例代码怎么利用它
2.1 QPainter、QPaintDevice、QPaintEngine三者到底是什么关系
QPainter是绘制指令的发出者，QPaintDevice是绘制目标，QPaintEngine则是真正执行绘制的驱动引擎。你可以把QPainter理解成一支笔，把QPaintDevice理解成画布，把QPaintEngine理解成拿着笔在画布上落墨的那只手。这个类比虽然粗糙，但能帮你记住核心关系：笔不应该直接接触画布，所有绘制行为都通过“手”来完成。
在2D Painting示例里，QPaintDevice通常是QWidget本身。你在paintEvent里做的每一件事，本质都是对widget发起绘制请求，而系统负责把请求转换成实际的像素变化。你可能永远不需要直接调用QPaintEngine，但你需要理解，不同设备（QWidget、QImage、QPixmap、QOpenGLWidget）对应的引擎实现是完全不同的。同样的绘制代码，在QWidget上走CPU软渲染，在QOpenGLWidget上走GPU管线，效果和性能天差地别。
2.2 为什么paintEvent是所有绘制的起点
很多初学者会犯一个经典错误：在构造函数里调用QPainter去画图。这在Qt里行不通，因为此时窗口尚未完成映射，绘图设备还没有准备好接收绘制指令。正确的做法是重写paintEvent，把所有绘制代码放在里面。2D Painting示例里每个子工程都遵循这个规则，方法名可能是paintEvent或paint，但思想一致。
paintEvent不是程序主动调用的，而是事件循环在处理窗口系统消息时自动触发的。你主动触发重绘的手段是调用update()。一个常见的认知误区是“update()会立即执行重绘”，实际上update()只是给事件系统打标记，请求尽快派发一个绘制事件，真正的绘制在事件循环返回后才会发生。这个延迟在某些高频交互场景下反而帮你节省了性能，因为事件系统会把多次相邻的update()请求合并成一次重绘。所以在示例的交互代码里看不到反复调用update()刷屏的情况，它只在需要刷新内容时才调用。
2.3 示例中的抗锯齿处理，为什么默认建议打开
在basicdrawing子示例里，绘制代码通常能看到painter.setRenderHint(QPainter::Antialiasing, true)。这条语句的作用是让QPainter在绘制几何边缘时采用像素级平滑过渡，而不是简单的二值化锯齿。效果上的差异非常直观：同样的斜线，不开抗锯齿时边缘呈现明显的“阶梯感”，开了之后边缘平滑圆润。
这里有个细节值得注意：不是所有绘制操作都受抗锯齿开关影响。受影响的以直线、曲线、多边形边界、文字轮廓为主。对于纯水平、纯竖直的矩形边界，抗锯齿开不开几乎看不出区别。有些初学者设置了抗锯齿却发现效果没变，大概率是画的是矩形边缘，而不是斜线或曲线。这个特性在示例里没有专门标注，但如果你自己动手画斜线对比，30秒就能看明白。
抗锯齿也有代价。它会让绘制性能有所下降，尤其是大批量几何填充时。示例代码并不避讳性能问题，但它的场景决定了不需要刻意优化。在真实项目里，我的经验是：静态内容打开抗锯齿，频繁变动的大批量图元关闭抗锯齿，必要时通过QPainter::RenderHint在运行时切换。
3. 拆解basicdrawing：基本图元的绘制细节和状态管理
3.1 画笔和画刷的选择，决定了绘制风格
看basicdrawing的代码时，你会发现它花了不少篇幅在构造QPen和QBrush上。QPen控制线条的宽度、颜色、样式（虚线、实线、点线），QBrush控制填充的颜色和纹理。二者是QPainter最核心的“属性设置”，在绘制前配置好，绘制指令发出后，图元自然按照当前属性渲染出来。
一个很容易被忽略的参数是QPen的capStyle和joinStyle。capStyle决定线段端点的形状，joinStyle决定折线拐角处的连接方式。比如画折线统计图时，把joinStyle设为RoundJoin能避免折线拐角处出现尖刺或断裂；画网格线时，把capStyle设为FlatCap可以防止端点突出导致坐标错位。这些细节在示例代码里只是轻轻带过，但它们在实际开发中的出场率非常高。
3.2 绘制坐标与窗口尺寸的弱耦合——示例为何这么做
你会发现示例里的图元坐标基本都是写死的常量。例如一个矩形的范围可能是QRect(20, 20, 200, 100)。这看起来“不够动态”，但其实是有意为之。因为示例的目标是演示QPainter的能力，而不是教学布局计算。如果坐标写得过于动态，读者反而搞不清楚参数变化对图形的影响。
但你要特别注意：真实项目中不能这么写。把坐标写死在paintEvent里，一旦窗口尺寸变化，图形要么被裁剪，要么产生大块空白。标准做法是从size()或QRect(rect())中动态计算绘制区域，再根据逻辑尺寸做比例换算。我见过很多自绘控件出现“窗口最大化后图形挤在左上角”的问题，根源就是坐标硬编码。2D Painting示例的坐标写法，看看就行，不要照搬到生产代码里。
3.3 QPainterPath：复杂图形的拼装方式
painterpaths子示例专门演示QPainterPath的用法。QPainterPath用类似“记录一笔一画”的方式描述复杂几何形状，可以组合线段、二次贝塞尔曲线、三次贝塞尔曲线、矩形、椭圆等。最麻烦的图形参数拼装，用QPainterPath就能显著简化。
比如画一个圆角缺口的标签背景，你要用drawRect会很别扭，但用QPainterPath可以依次moveTo、lineTo、arcTo，最后closeSubpath，把轮廓“画”出来。示例代码里还演示了多个子路径的组合，这给自绘列表项背景、仪表盘指针、气泡消息框这类界面元素提供了非常直接的参考。我在做某个跨平台系统的自定义菜单项时，就用QPainterPath构造了带箭头的会话气泡，核心思路就是从painterpaths这个子示例里学的。
4. 深度体验gradient子示例：渐变类型的原理与选择
4.1 线性渐变：坐标区间决定颜色走向
gradient子示例演示了QLinearGradient、QRadialGradient和QConicalGradient三类渐变。很多人会用QLinearGradient，但搞不清参数是绝对坐标还是相对坐标。答案是：QLinearGradient需要传入两个逻辑坐标点，渐变方向就沿着这两个点的连线方向，起始点和终点之外的区域则按设置的spread模式伸展。示例里会构造类似QLinearGradient grad(0, 0, 100, 100)的对象，意思是颜色从(0,0)沿对角线过渡到(100,100)。
要注意，渐变坐标是相对于QPainter当前坐标系而言的。如果你对painter做了平移变换，渐变范围会跟着平移。这是“渐变为什么位置和预期不一致”的常见原因。遇到渐变位置不对，别急着怀疑颜色值，先检查坐标系是否已经发生了变换。我在项目里用渐变绘制进度条背景时，就曾因为坐标变换漏算了一个margin，导致渐变偏移了小半个控件宽度。
4.2 径向渐变与锥形渐变：高光、光源表现的首选
QRadialGradient通过圆心坐标、半径、焦点坐标三个参数控制渐变形态，适用于模拟高光、阴影、球体立体感。QConicalGradient则围绕中心点从起始角度旋转360度生成渐变，颜色沿圆周方向变化，适合仪表盘、转盘、雷达扫描效果。
示例代码在这部分最值得学习的不是怎么调三个渐变，而是观察它们的“边界行为”。径向渐变在半径外延伸出的区域，默认使用边界颜色填充；锥形渐变在起始角处存在一个“接缝”，这是数学定义决定的，无法完全消除，只能通过调整起始角度和颜色过渡来视觉弱化。这些小细节，你不实际跑一遍示例，很难在文档里注意到。
4.3 渐变对象的生命周期与绘制性能
渐变对象的构造开销比想象中高，尤其是包含大量颜色断点的渐变。如果你在paintEvent里每帧都创建一个QLinearGradient，性能会明显下降。示例代码里渐变对象通常是局部构造，因为它一次只画几个图形，但你要在自定义控件中画大量渐变对象时，务必把不频繁变化的渐变对象缓存成成员变量或静态对象，只在参数变化时重新构造。
我遇到过一个问题：一个列表控件的选中项背景用了QLinearGradient，但每帧重绘时都重建渐变，导致滚动时CPU占用居高不下。缓存渐变对象之后，绘制开销几乎降了一个数量级。这个优化思路在官方示例里没有直接展示，但它属于那种“代码量小、效果惊人”的必学技巧。
5. composition子示例的价值：图像合成的模式选择
5.1 合成模式不是图层混合，而是像素级运算
composition子示例演示了QPainter::CompositionMode，这些模式决定了新绘制的像素如何与已有像素进行混合。初学者容易把它们想成Photoshop里的“图层混合模式”，其实不完全是。Qt的CompositionMode基于数学公式操作RGBA通道，例如SourceOver是“源覆盖目标”，DestinationOver是“目标覆盖源”，SourceAtop则是“源仅绘制在目标不透明的区域上”。
示例代码里通常会用两张不同的图片或色块做叠加，你切换下拉框时能直观看到不同合成模式的变化。我觉得最有价值的理解方式是：把每个合成模式想象成一个二元运算，输入是“已有的像素”和“新画的像素”，输出是“最终显示在屏幕上的像素”。至于这个运算具体是加、减、乘还是按通道混合，Qt文档里有完整公式，但实验观察更直觉。
5.2 适合用合成模式的真实场景
合成模式最常用的场景之一是绘制截图、缩略图、图像水印。比如你想给图片加一个半透明遮罩，可以用SourceOver配合半透明QBrush完成。你想做一个“橡皮擦”效果，可以切换到Clear模式，把绘制区域的像素直接清零。你还可以用Plus模式把两张图像做亮部叠加，用来模拟光效。
我在这里给你一个实操建议：先在草稿纸上写出“目标效果”的像素公式，再查一下Qt提供的CompositionMode中哪个公式与之匹配。别凭感觉猜。比如你想实现“颜色减淡”，文档里对应的模式可能是Plus或者Screen，两者效果差异巨大，不实际测试很容易翻车。
5.3 合成模式对绘制引擎的依赖
合成模式在不同QPaintEngine上的支持度不一样。QImage、QWidget、OpenGL窗口三者能用的合成模式集合有差异。示例运行在QWidget上没什么问题，但如果你的目标平台是OpenGL渲染，部分高级合成模式可能会被降级处理甚至忽略。这属于“换环境就出事”的典型场景。
避免这个问题的方法有两个：一是尽量用SourceOver、DestinationOver、Clear这些基础模式，它们的通用性最好；二是在程序启动时检测当前设备支持的合成模式列表，做兼容降级。官方示例不会教你这些，但你的项目只要跨平台，就早晚会遇到。
6. 自己动手改造示例：把四个子工程串成自己的画板
6.1 从看代码到改代码的最小路径
光看示例代码的收获是有限的。我建议你按这个顺序动手改造：
- 修改basicdrawing里的坐标和颜色值，观察变化。
- 在paintEvent里追加一个自己设计的图形，比如五角星。
- 给渐变子工程加一个“渐变动画”，用QTimer周期性改变渐变参数。
- 在composition子工程里加载自己的两张图片，测试合成效果。
- 把painterpaths里画的路径保存为QPicture或QImage，观察失真情况。
我自己的改造经验是从一个“仿真仪表盘”开始的。先把示例里的渐变和路径代码移植过来，再替换成角度表盘的数据绑定逻辑。移植过程能帮你检验一个关键点：你是否理解了代码的依赖关系。如果你把某一个子工程的代码复制到新工程后，能顺畅编译并达到预期效果，说明你真的看懂了；如果报错或者显示异常，回头重新检查状态管理和设备初始化部分。
6.2 在改造中深入理解坐标变换
改造过程一定要主动引入坐标变换：translate、scale、rotate。2D Painting示例里可能只是间接用到这些，不会系统讲解，但你要自绘任何有点难度的控件，离开坐标变换寸步难行。
举个例子，画一个仪表指针，最省事的做法不是算好多边形每个顶点的绝对坐标，而是先把坐标系平移到圆心，再旋转到当前角度，然后直接沿x轴画一个矩形。绘制代码的核心只有三四行，剩下的交给变换矩阵。这样写不仅清晰，还能非常方便地做动画插值。我自己在改造示例时，专门加了一个小测试页：鼠标拖动时实时变化旋转角度，指针跟着转动。完成这个，你对坐标系的理解就到位了。
6.3 学会从示例里提炼可复用的绘制工具类
阅读官方示例，你的目标不能只停留在“看懂”，还要学会“提取”。比如basicdrawing里的画笔设置、painterpaths里的路径构造、gradient里的渐变布局，都可以封装成自定义控件的绘图工具函数。我在实际项目中就把渐变背景绘制、圆角路径遮罩、图形合成叠加这几段逻辑抽成了独立的静态方法，放在一个叫GraphicsHelper的类里，项目里的多个自绘控件直接复用。
封装过程中注意一点：不要在工具类里依赖具体业务数据。函数只接收绘制参数，不接收业务对象。比如“绘制圆角矩形背景”的函数接收QRectF、半径、颜色就可以，不要接收某个订单对象。这样封装出来的东西才能真正被复用。
7. 常见问题与排查技巧实录
7.1 绘制内容不显示的几种原因
把示例代码搬进自己的工程后，最常见的问题是“什么都没画出来”。排查顺序应该是：
- 是否重写了paintEvent，并且调用了QWidget::paintEvent？如果不调用基类实现，背景可能不清理。
- 绘制代码是否真的被执行？可以在paintEvent里qDebug打印验证。
- QPainter是否成功begin？只要构造QPainter对象时没有显式指定设备，begin就是隐含的，但要留意绘制期间有没有其他地方也构造了QPainter。
- 坐标是否超出可视区域？特别是在有滚动区域或布局边界时，逻辑坐标可能偏移。
一个容易被忽略的点是窗口的autoFillBackground属性。如果它被关闭，窗口背景可能不刷新，旧的绘制内容会残留。出现“图形拖影”或“叠影”时，优先检查这个属性。
7.2 图形闪烁怎么处理
自绘界面闪烁的根源通常是“先擦除背景，再绘制内容”的两个阶段在视觉上形成反差。你可以在示例代码的改造中尝试设置setAttribute(Qt::WA_OpaquePaintEvent, true)，告诉系统绘制事件不透明，后续就不需要擦除背景。这在绝大多数桌面平台上能大幅降低闪烁。另一个办法是使用QBackingStore手动管理缓冲区，但日常应用中用OpaquePaintEvent就够用了。
需要强调的是，OpaquePaintEvent并非万能。如果你绘制内容本身是半透明的，设置了这个属性反而会让合成结果出错。所以它只适合完全覆盖背景的控件。判断标准很简单：你的绘制代码是否把整个控件区域都用不透明颜色填满了。不满足就别开。
7.3 坐标变换叠加导致的绘制位置错乱
如果你发现自己画的图形位置越来越偏离预期，问题基本出在“变换状态累积”。QPainter的坐标变换不是“临时生效”的，除非你用save()和restore()把状态入栈出栈，否则变换会持续影响后续所有绘制操作。示例代码虽然简单，一般不会遇到这个问题，但你自己改造时加了旋转、缩放后，一定要成对使用save()和restore()。
我的习惯是：每次绘制一个独立图元之前先save()，绘制完成后立即restore()，保证状态整洁。这个习惯一开始会觉得麻烦，但当你同时处理几十个图元时，就会体会到它带来的确定性。而且这个习惯也能防止你在多线程环境中因为状态共享导致的莫名其妙问题。
7.4 半透明效果与抗锯齿同时开启时的叠加问题
半透明绘制和抗锯齿一起使用时，边界容易出现“白边”或“灰边”。这是因为抗锯齿产生的边缘像素本身带有透明度，与半透明填充叠加后会出现双重混合。解决办法有两个：一是在绘制边缘时关闭抗锯齿，二是使用统一的预乘Alpha颜色值。
这个细节在示例里不太容易暴露，因为你看到的渐变和路径大多是完整不透明的图形。但在实际开发里，圆角头像、阴影浮层、玻璃拟态背景都逃不开这个坑。排查时多用取色工具看看边缘像素的RGBA值，能帮助你快速定位到底是哪一步混合出了问题。
8. 从2D Painting示例里带走什么，以及后续怎么扩展
8.1 我反复回看这个示例的收获清单
把这个示例完整跑过、改过之后，我总结下来的核心收获是：
- 绘制代码必须集中在paintEvent里，状态管理与重绘触发要分离。
- QPainter的绘制结果同时受QPen、QBrush、RenderHint、坐标变换、CompositionMode影响，任何一个状态改动都会牵一发动全身。
- 官方示例代码结构简单，但处处体现“职责单一”的设计思想，比很多业务代码干净得多。
- 用QPainter做自绘，本质是把复杂视觉需求拆解成图元、路径、渐变和合成操作。
8.2 你还可以往哪些方向扩展
如果你已经吃透了2D Painting，下一个建议方向是：
- 结合QPropertyAnimation写一个带动画的绘制控件，把paintEvent里的参数随时间插值。
- 把绘制结果离线渲染到QImage，再保存成PNG，做一个“导出图片”功能。
- 尝试用QOpenGLWidget替换QWidget，感受同一套QPainter代码在GPU加速下的表现。
- 把QPainter的能力迁移到QGraphicsView框架中，理解场景、视图、图元三者的分工。
我个人的体会是，官方示例的价值不止于“能运行”，更在于它提供了一种“最小的完整实现”。读它，你不只是学API，而是在观察一个老练的Qt开发者怎么组织绘制代码、怎么安排状态、怎么选择坐标策略。这种“从代码里品设计”的训练，比刷十篇零散的教程都管用。你按本文的顺序把4个子工程逐行过一遍，再动手改出几个自己的效果，QPainter这套东西基本就长在脑子里了。
