很多人学Qt都是从打开一个Demo开始，但大部分人的路线是：跑起来、截个图、关掉。我一开始也是这样，直到某个项目里需要在自定义控件上绘制一个带渐变、阴影、不规则路径的图表界面，才发现连QPainter的坐标系都没完全搞明白。后来把Qt 5.14.2自带的2D Painting示例从头到尾拆了一遍才真正开窍。这篇博客就是记录我拆解这个示例的过程，内容包括示例的运行效果、核心类结构、QPainter绘图机制的底层理解，以及我实际运行和改造成项目代码时踩过的坑。如果你正准备入门Qt自定义绘图，或者想系统的搞懂图形绘制的底层流程，这篇文章可以帮你省下不少弯路。
1. 为什么我建议每个Qt新手都先跑一遍2D Painting示例
先说说我眼中的2D Painting到底是什么。它是Qt自带示例集中位于widgets/painting目录下的一个标准示例，打开后你会看到一个类似画布的主窗口，左侧是各种画笔、画刷、渐变的演示区域，右侧是对应的控制面板，可以切换不同的图形形状、笔刷样式、渐变方式，画面会实时变化。
这个示例展示的东西覆盖了Qt 2D绘制的核心知识面：基本图形绘制、画笔（QPen）样式、画刷（QBrush）样式、三种渐变、抗锯齿开关、图形变换（平移、旋转、缩放、扭曲），以及合成模式。换句话说，凡是你在Qt里手动画界面需要用到的绘制概念，它几乎都做了可视化展示。对于新手来说，它就像一本配了运行环境的活教材，可以边改参数边看效果，比单纯看文档直观得多。
我当时跑通这个示例之后，又把它里面的核心代码拿出来逐行分析，才发现它并不只是一个“能跑”的demo，而是非常值得读源码的教学案例。它的设计其实很规范：一个控制窗口（MainWindow），一个绘制画布（PaintWidget），一个形状枚举（Shape），通过QPainter在paintEvent中根据当前配置绘制不同形状和效果。
这类示例最容易被忽略的价值在于，它把这些看起来零散的绘制API串成了一个完整的“状态管理”流程。你需要理解的不只是某个API怎么用，而是UI控件状态变化之后，如何触发生成一张新画面。这个思路放到实际业务里，其实就是你自定义控件的全部工作模型。
所以我的建议很直接：如果你刚开始接触Qt，别急着写复杂项目，先把2D Painting示例跑起来，再花一个下午把它的源码逐行读一遍，把每个控制参数和绘制结果对应起来。这个步骤完成后，你再看其他绘图相关代码，基本不会有理解障碍了。
2. 示例文件结构拆解：从工程文件到PaintWidget绘制流程
2.1 工程文件与目录布局
在标准安装的Qt 5.14.2环境下，示例位于安装目录的Examples/Qt-5.14.2/widgets/painting/painter子目录中。整个工程的文件并不复杂，核心文件包括：
painter.pro：qmake工程文件，负责指定源文件、头文件和Qt模块依赖；main.cpp：程序入口，创建MainWindow并显示；mainwindow.h/.cpp：主窗口，负责布置左侧控制面板和右侧绘制区域；paintwidget.h/.cpp：核心画布控件，重写paintEvent，根据状态执行绘制；helper.h/.cpp：定义Shape枚举、Painter绘图类；settings相关代码：管理当前绘图配置（形状、颜色、渐变、变换等）。
我记得第一次看这个目录时，并没有立刻找到所有绘制代码，因为示例刻意把“状态定义”和“绘制动作”拆开了。MainWindow只负责接收用户操作并保存配置，真正的绘图逻辑都集中在Painter::draw和PaintWidget::paintEvent里。这个分层方式和我们在真实项目中做自定义控件的思路是一样的：界面只负责输入，绘制层只负责输出。
如果你是用Qt Creator打开这个工程，建议先直接点击运行。构建时注意选择与你机器匹配的套件，我用的环境是Windows下的MinGW 64-bit套件，直接点绿色运行按钮就能出来窗口。如果弹出缺少QT += widgets之类的报错，检查一下.pro文件里是否包含了对应的模块声明，5.14版本的QApplication和控件类都已经移到widgets模块里了。
2.2 核心入口MainWindow与状态配置
MainWindow做的事情直观但容易忽略：它维护了一个配置对象，记录当前选中的Shape、Pen属性、Brush属性、渐变类型、变换开关、抗锯齿开关等。左侧面板上的各种下拉框、复选框、滑块，改动之后会更新这个配置对象，然后调用paintWidget->update()触发重绘。
这里有个很关键的设计点：update()不是同步重绘的。它只是给Qt的事件循环打了一个“需要重绘”的标记，等到主循环空闲时才真正调用paintEvent。这样设计的好处是高频操作（比如拖动滑块）不会让界面卡顿，Qt会把多次update()合并成一次实际绘制。我在早期的代码里曾经误以为update()会立刻执行重绘，导致依赖绘制结果做逻辑判断，结果调试了半天。如果你也这么干过，记住这个机制，它就是一个异步标记。
2.3 PaintWidget与paintEvent的绘制流程
PaintWidget继承了QWidget，并把自身设置成视口尺寸。它重写的paintEvent(QPaintEvent *)是整个示例最核心的入口。
每次重绘时，它会先创建一个QPainter对象，再对helper执行绘制调用。示例里的Painter::draw函数负责所有具体图形的绘制，按配置枚举值分发到不同的绘制分支：矩形、椭圆、三角形、文本、菱形、直线等。整个流程可以简化为：
- 依据控件尺寸计算绘制区域中心点；
- 保存当前绘制状态，设置抗锯齿、变换矩阵、画笔、画刷；
- 根据
Shape枚举调用对应的绘制函数； - 恢复绘制状态，结束绘制。
这里要重点提一下save()和restore()。QPainter是一个有状态的对象，画笔、颜色、变换矩阵、合成模式都会持续生效。如果你在绘制过程中改变了状态而没有恢复，后续所有绘制的元素都会受影响。示例中的做法是在draw函数开头保存状态，在末尾恢复，这样既不影响外部调用方，也让内部各绘制分支互不干扰。你可以在自己代码里用大括号限定QPainter作用域来达到类似效果，但显式save/restore的可读性和可控性更高。
我在读这份代码时最在意的部分，是示例对坐标系的理解。控件坐标原点默认在左上角，x向右增大，y向下增大。示例里用painter->translate(rect.center())把原点移到了控件中心，然后所有图形都按中心对称的方式来画。这种变换在手动画对称图形时非常好用，因为可以避免反复计算偏移量。稍微延伸一下，如果你要绘制时钟表盘、雷达扫描、仪表指针这类元素，这个技巧能省掉大量坐标换算工作。
2.4 Painter类的绘制分发
Painter::draw函数根据Shape枚举值进入不同分支。每个分支都创建对应的QPainterPath或直接调用drawRect、drawEllipse、drawLine等基础绘图API。QPainterPath值得单独说一下，它可以被理解为“一个可复用的绘图指令集合”，你可以在路径中依次添加直线、弧线、贝塞尔曲线，然后再用drawPath一次性输出。示例中很多复杂图形，比如圆角矩形、连线图、五角形路径，都是先构造路径再绘制，而不是直接用现成的绘图API。原因是路径绘制更灵活，并且可以被fill、stroke、clip多种方式复用。
很多初学者容易跳过QPainterPath，因为直接画矩形和线条就能应付简单需求。但在实际项目里，不规则控件裁剪、自定义气泡框、曲线图表，基本都要靠它。2D Painting示例虽然没有专门讲解路径机制，但它的绘制代码本身就是在展示路径的典型用法，只是它没有敲黑板告诉你“这里用的是路径，请注意”。
3. QPainter绘制机制的几个关键理解
3.1 为什么绘制代码必须写在paintEvent里
这是新手最容易困惑的问题。为什么Qt不让你在任意函数里直接画？原因是Qt的绘制系统依赖于窗口系统的底层“曝光”机制。当窗口被遮挡、放大缩小、最小化恢复时，系统会要求组件把损坏的区域重新绘制一遍。如果绘制不在paintEvent里完成，窗口每次被遮挡再露出，内容就会变成空白或者产生残影。
2D Painting示例的paintWidget每次收到事件都会完整重绘。它在paintEvent里重新计算全部图形，所以在窗口缩放时效果始终是清晰的。实际项目中有时会因为性能考虑，把绘制结果先缓存到QPixmap，在paintEvent里直接drawPixmap，但无论如何第一次内容生成必须在事件回调里完成。
我调试过很多次类似问题：界面上明明调用了某个绘制函数，但运行后什么都没有。原因基本都是绘图代码放在了构造函数或者业务回调里，窗口一旦重绘内容就消失了。如果你也遇到这种“偶尔出现，一遮挡就消失”的问题，先看看绘制代码是不是在paintEvent里。
3.2 设备坐标系与逻辑坐标的偏差
Qt的坐标系统有两层：逻辑坐标系和物理设备坐标系。在默认情况下两者是一致的，但遇到高DPI屏幕、变换矩阵时就不一样了。2D Painting示例通过scale变换让图形放大缩小，本质上是修改了逻辑坐标到物理坐标的映射关系。此时QPainter在绘图时会把你的逻辑坐标乘以当前变换矩阵，再映射到屏幕上的物理像素。
举个例子，你用painter->scale(2, 2)之后，再画一个从(10, 10)到(30, 30)的矩形，它实际上会占据屏幕上(20, 20)到(60, 60)的区域。这个机制在做缩略图、图表缩放时非常有用，但也容易踩坑，尤其是你在绘制区域里还使用了鼠标坐标时。鼠标返回的是控件坐标，而你的绘图坐标可能已经经过变换，二者不统一就会画偏。解决思路一般是把业务逻辑里的坐标统一用“原始逻辑坐标”，只在最后画到QPainter时才应用变换。
3.3 save/restore与绘制状态栈
QPainter内部维护了一个状态栈。save()会把当前画笔、画刷、字体、变换矩阵、合成模式、裁剪区域全部压入栈内，restore()会从栈顶弹出并恢复。这个机制是示例代码能够优雅切换各种效果的关键。
假设你不使用save/restore，那么在一个绘制函数里改动了画笔颜色，之后所有绘制都会用这个颜色，除非你手动再改回来。状态一多就会混乱。尤其是当你封装公共绘制函数供多个控件调用时，一个函数不小心污染了全局绘制状态，后面的所有输出都会异常。所以我的建议是，每个独立的绘制分支，入口处save()，出口处restore()，保持状态干净。这算不上高级技巧，却能避免大量低级但隐蔽的显示问题。
3.4 抗锯齿与绘制质量
示例中有一个“Antialiasing”复选框，勾选与不勾选的效果差异肉眼可见。开启抗锯齿后，图形边缘会通过半透明像素过渡，消除“锯齿感”，视觉效果平滑许多。QPainter的对应设置是：
painter->setRenderHint(QPainter::Antialiasing, true);除了Antialiasing，还有TextAntialiasing、SmoothPixmapTransform等渲染提示。具体到2D绘图场景，Antialiasing对形状和曲线的作用最明显。但要注意，开启抗锯齿会增加额外计算量，对大量实时绘制（比如高频刷新图表）有明显开销。我通常的做法是：静止画面开启，高频动画且性能敏感时关闭，或者采用“非核心技术用位图缓存，位图本身开启平滑变换”的方式折中处理。
4. 影响绘制效果的三件小事：画笔、画刷与合成模式
4.1 QPen样式：不只是颜色和粗细
2D Painting示例的右侧面板中，Pen部分可以设置颜色、线宽、线型（实线、虚线、点线等）和笔帽样式。QPen看起来简单，但有很多细节会影响最终效果。
线型选择上，Qt::DashLine等虚线样式在setStyle里直接指定，但线宽大于1时，虚线段的实际长度受dashPattern控制。示例里没有深入演示，但你在绘制边界框、坐标轴、网格线时一定会用到。比如网格线用1像素实线，辅助线用虚线，重点区域用宽一点的半透明线，这些视觉层次全靠QPen调出来。
另外圆角连接和笔帽样式在绘制粗线条折线时尤为关键。默认的Qt::MiterJoin在折线角度尖锐时会产生尖刺延伸，改成Qt::RoundJoin则更圆润。如果绘制的是监控折线图或者折线路径，建议设置Qt::RoundCap和Qt::RoundJoin，能让线条看起来更自然。
4.2 QBrush样式：填充效果的变化
画刷负责封闭图形的填充。2D Painting示例中可以看到纯色填充、纹理填充和渐变填充的区别。QBrush不仅仅能设置颜色，还可以设置样式，比如Qt::CrossPattern、Qt::DensePattern等。在实际项目中，这些线性或蜂窝状纹理常被用来做半透明的覆盖图层，比如地图上的热区遮挡。
更常用的是渐变画刷，Qt提供了三种：线性渐变QLinearGradient、辐射渐变QRadialGradient、锥形渐变QConicalGradient。示例会分别展示这三种效果，并演示渐变方向和焦点位置的调整。用渐变做背景、做柱状图的高光、做进度条的光泽效果，都离不开它们。
使用渐变时有一个常见误区：渐变坐标是在逻辑坐标系里定义的，一旦你对QPainter做了缩放或平移变换，渐变效果也会跟着变化。示例里由于图形经过变换绘制，为了方便演示，在某些分支里会重新计算渐变坐标，保证渐变方向和形状比例匹配。你可以把这理解为“渐变也活在同一个坐标空间”，需要变换时别忘了重新映射。
4.3 合成模式：叠加出来的效果
合成模式决定新绘制的像素如何与已有像素混合。默认的SourceOver模式就是普通覆盖，新内容覆盖旧内容，但其他模式如Plus（叠加变亮）、Multiply（正片叠底）、Difference（差值）会产生完全不同的视觉效果。2D Painting示例中提供了一个合成模式下拉框，你可以直接看到圆形、矩形等图形在重叠区域的混合效果。
这个特性的实战价值在于制作“发光”“投影”“高亮”等效果。比如用CompositionMode_Plus模式绘制柔和的半透明光晕，多次叠加之后会越来越亮；用CompositionMode_Multiply做纹理相乘，可以把渐变纹理映射到图形上。需要留意的是，合成模式对底层绘制有依赖，如果底层是QImage或QPixmap，不同图像格式对结果也会有影响。示例的绘制控件默认是不透明的，但如果你在做图层类的工具，建议给画布显式填充一个不透明底色，再叠加其他模式，否则容易出现意外的透明区域。
5. 构建运行这个示例时，我踩过的5个坑
5.1 中文路径导致构建失败
这是一个很常见的意外。把整个示例目录拷贝到带中文名的路径下，比如D:\测试代码\painter，Qt Creator在qmake阶段或编译阶段可能会报各种找不到文件的错误。原因是部分编译器工具链对非ASCII路径支持不好，或者生成的文件路径里出现中文导致依赖项解析异常。这种问题排查起来很迷惑，因为错误提示并不直接说有中文路径问题，而是报一些“无法打开文件”“cannot find -l”之类的错误。解决办法很简单：把代码放到纯英文路径下。看起来很低级，但真的能卡住很多人。
5.2 套件选择不对导致编译报错
Qt 5.14.2一般自带MinGW和MSVC两套编译链，装的时候可以都选。如果示例是用MinGW写的，你用MSVC打开，直接在构建时可能会遇到moc工具生成的头文件不匹配，或者glu32之类的链接错误。多数情况下，把构建套件切换成同系列的编译器就能解决。如果你非要用MSVC，可能需要重新执行qmake并清理缓存。我建议新手先统一用一套编译器，不要混着来，否则会分散学习精力。
5.3 高DPI屏幕上坐标偏移
在高分屏环境下（比如Windows显示缩放比例设为125%或150%），如果不做任何适配，2D Painting示例的图形可能出现轻微模糊或坐标偏移。原因是Qt需要感知物理DPI和逻辑DPI的比率。5.14版本中可以在main.cpp里设置：
QApplication::setAttribute(Qt::AA_EnableHighDpiScaling); QApplication::setAttribute(Qt::AA_UseHighDpiPixmaps);这样可以保证坐标系和像素图在不同缩放级别下保持一致。如果你在自己的绘图程序中遇到控件位置和鼠标点击位置对不上，而系统又开了缩放，很可能就是DPI适配没有处理。
5.4 在paintEvent之外调用QPainter
我自己早期犯过的错：在某个按钮点击回调里创建QPainter画布，想直接把内容画到控件上，结果窗口一刷新内容就消失，甚至控制台还会输出“QPainter::begin: Paint device returned engine == false”的警告。这个警告的意思很明确：当前设备不允许此时绘制。正确做法是把绘制代码放到paintEvent里，按钮点击只负责修改数据状态，然后调用update()请求重绘。如果你需要在按钮点击后立刻看到效果，update()加事件循环的异步机制已经足够了。
5.5 窗口缩放导致的闪烁问题
2D Painting示例本身不会闪烁，因为你用的是Qt::WA_OpaquePaintEvent或普通背景重绘。但如果你仿照它的模式绘制复杂、耗时的内容，在窗口放大缩小时会看到明显的闪烁。闪烁的本质是背景先被擦除，再绘制新内容，中间产生了白屏帧。解决思路有三个：一是在paintEvent里用双缓冲（QPainter绘制到QPixmap，再一次性drawPixmap到控件）；二是设置setAutoFillBackground(false)并手动绘制背景；三是用Qt::WA_OpaquePaintEvent告诉系统不要自动擦背景。实际项目里双缓冲最常用，稳定也最可控。
6. 把这个示例改造成项目级绘图组件时，我常用的思路
6.1 绘制内容缓存到QPixmap
2D Painting示例每次重绘都会重新计算所有图形，这对演示来说没问题，但到了真实项目里就会遇到性能瓶颈。我的习惯是：如果图形内容不是频繁变化，就先画到一个QPixmap上，作为“画布缓存”，然后在paintEvent里直接把这个QPixmap贴到控件上。
QPixmap cachePixmap(size(), QPixmap::devicePixelRatio()); cachePixmap.fill(Qt::transparent); QPainter painter(&cachePixmap); // 在这里画所有内容 painter.end(); QPainter widgetPainter(this); widgetPainter.drawPixmap(0, 0, cachePixmap);这样做的最大好处是重绘开销变成一次像素拷贝，而不是重新执行几十次绘制指令。尤其在绘制复杂图表、网格、纹理时，性能提升非常明显。
6.2 用增量更新代替全量重绘
如果你的绘图组件需要频繁更新，比如鼠标拖动画笔轨迹、实时显示波形、进度动画，全量重绘就很浪费。Qt提供了QWidget::update(const QRect&)接口来指定需要更新的局部区域。你可以只对“新增的那一小块区域”请求重绘，系统会把这个区域裁剪出来，只绘制这部分内容。配合位图缓存，这种增量更新策略能让界面流畅度提升一个档次。
不过要注意，如果图形内容做的是整体平移、缩放这类全局变换，增量更新就不划算了，反而是全量重绘更直接。判断标准很简单：局部变化用局部更新，整体变化用全量更新，不要在局部更新逻辑里画一大堆全局元素，那只会让代码变复杂。
6.3 让业务数据和绘制逻辑解耦
2D Painting示例里，MainWindow持有“配置”，PaintWidget根据配置绘制。这个分层关系可以直接迁移到业务项目。我现在的习惯是定义独立的“数据模型”结构体或类，比如图表数据、节点列表、样式配置，然后让绘制类只依赖这个模型。这样当你需要换肤、换数据源、支持多视图时，绘制代码几乎不用改。
解耦的另一个好处是便于单元测试。纯绘图逻辑如果要验证，往往需要截图对比或者肉眼观察，但如果你把“模型如何转换成绘制指令”单独抽出来，就可以在无界面的环境下测试指令序列是否正确。对于复杂绘图系统，这是一个很实用的工程化解法。
6.4 如果再深入一点：自定义控件与交互
示例本身不涉及鼠标交互，但实际绘图组件几乎必然要处理鼠标事件。一个典型扩展是：在PaintWidget上重写mousePressEvent、mouseMoveEvent，将鼠标坐标转换为逻辑坐标，然后更新模型并触发重绘。这个过程中最容易翻车的点就是坐标系转换，尤其当你使用了painter->scale或者painter->rotate之后，鼠标坐标直接被视为绘制坐标，画出来的图形位置就会错乱。
正确的做法是在事件处理函数里做矩阵逆变换，把光标位置映射回“逻辑坐标”，再交给业务逻辑处理。Qt的QTransform支持求逆矩阵，比如：
QTransform transform; transform.translate(rect.center().x(), rect.center().y()); transform.scale(scaleFactor, scaleFactor); QPointF logicalPos = transform.inverted().map(event->pos());这部分内容已经超出2D Painting示例的范畴，但只有走到这一步，你才真正把示例里的那些变换技巧应用到了实际项目中。
总的来说，2D Painting示例的价值并不是让你记住几个绘制API的用法，而是帮你建立一套“状态管理、事件触达、绘制执行”的完整心智模型。我后来做自定义仪表盘、股票K线图、流程图编辑器时，底层思路基本都能追溯到对这个示例的拆解。如果你现在正卡在绘制坐标混乱、重绘逻辑不清、窗口更新闪烁这类问题上，回到这个示例，把每一步的触发关系和状态变化理清楚，多半能找到答案。
