简介面向Qt/C开发者的交互式绘图Demo基于QGraphicsView、QPainter与QGraphicsRectItem完整演示了在Qt 5.15.2与VS2019环境下用鼠标绘制矩形的技术方案。工程支持同时绘制一个或多个矩形鼠标悬停可按住拖动图元拖拽边缘可调整宽高按住Ctrl滚动滚轮可对矩形缩放右键菜单可直接删除或保存且可扩展为多边形等自定义图形适合需要实现图像标注、ROI选取或图形编辑器功能的开发者参考。压缩包共16个文件包含5个头文件与5个C源文件另有ui界面文件、工程配置vcxproj、qrc资源及rc资源等辅助文件整体约18KB工程骨架完整便于理解View/Scene/Item架构与事件过滤机制。目前已有2348人学习下载。通过该Demo可快速掌握QGraphicsView的事件处理、图元拖拽与缩放、右键菜单集成等关键知识点能有效缩短同类功能的开发时间。1. GraphicsView 下用鼠标绘制矩形一次把事件、画布和图元串起来的实战把鼠标按下、拖动、松开翻译成屏幕上一条实时伸缩的矩形框是 GraphicsView 系列组件最常见的入门需求。但真用 QPainter、QGraphicsRectItem 在 Qt 里动手时很多人会卡在同一个路口为什么我明明画了矩形它却不在鼠标的位置上为什么视图稍微缩放边框就粗细不一这篇笔记围绕 GraphicsView、QPainter、QGraphicsRectItem 三者的配合把用鼠标绘制矩形的完整链路拆开——先理清坐标系的换算规则再给两条可复现的落地路径最后把命中率最高的几个坑逐个标记出来。适合正在写标注类工具、截图框选功能或者刚接触 GraphicsView 框架的开发者。2. 坐标换算与事件时序鼠标画矩形前必须搞定的两个底层问题很多人的第一版代码长这样按下时记录event-pos()移动时用QRect(start, current)画一个矩形松开时把这个矩形直接塞给QGraphicsRectItem。结果矩形位置飘忽不定时对时错。问题几乎都出在两个底层点上坐标没有统一到同一个空间事件没有按正确的顺序消费。2.1 viewport、场景、图元三层坐标怎么换算QGraphicsView内部有三层坐标视图自身的viewport()坐标、QGraphicsScene的场景坐标、QGraphicsItem的本地坐标。鼠标事件首先落在 viewport 上此时拿到的是相对窗口左上角的像素坐标单位是像素。而场景坐标是浮点数决定了整个图形世界的位置。两者之间隔着滚动条偏移、视图缩放比例、变换矩阵直接混用必然错位。坐标系来源典型取值用途viewport 坐标event-pos()QPoint整数像素判断点击了屏幕哪个位置场景坐标view-mapToScene(pos)QPointF浮点决定矩形在图形世界中的真实位置item 本地坐标item-mapFromScene(scenePos)QPointF决定矩形相对于图元自身的位置最常见的换算写法是这样// viewport 坐标 - 场景坐标 QPoint viewportPos event-pos(); QPointF scenePos view-mapToScene(viewportPos); // 场景坐标 - item 本地坐标 QPointF itemPos rectItem-mapFromScene(scenePos);参数说明mapToScene接收的是 viewport 内的位置返回的是场景坐标如果 view 有缩放、平移、旋转这个换算会自动把变换包含进去。mapFromScene反过来用当图元设置了pos()或者本身带变换时矩形坐标必须转成 item 本地坐标再调用setRect()。如果你的图元没有设置pos()也没有任何变换那么 item 本地坐标和场景坐标是重合的这也是很多示例代码直接拿场景坐标设置矩形的原因。记住一条判断规则只要矩形最终是交给QGraphicsRectItem::setRect()就要确保传入的值属于 item 本地坐标空间。在没有位移、没有缩放的默认情况下它等于场景坐标一旦你给图元设置了setPos()或者对 view 做了缩放就要用mapFromScene转换。2.2 press→move→release 三个阶段的事件分工与参数设置鼠标画矩形是一个典型的三阶段交互按下时记录起点移动时更新预览松开时提交最终结果。mousePressEvent里只做一件事——记录起点并标记开始绘制mouseMoveEvent里根据当前点和起点计算矩形刷新预览mouseReleaseEvent里把矩形正式写入场景清理临时状态。void DrawRectView::mousePressEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { m_drawing true; m_sceneStartPos mapToScene(event-pos()); update(); } QGraphicsView::mousePressEvent(event); } void DrawRectView::mouseMoveEvent(QMouseEvent *event) { if (m_drawing) { m_sceneCurrentPos mapToScene(event-pos()); update(); // 触发 drawForeground 重绘橡皮筋 } QGraphicsView::mouseMoveEvent(event); } void DrawRectView::mouseReleaseEvent(QMouseEvent *event) { if (m_drawing event-button() Qt::LeftButton) { m_drawing false; commitRect(); // 生成正式的 QGraphicsRectItem } QGraphicsView::mouseReleaseEvent(event); }参数说明m_sceneStartPos和m_sceneCurrentPos都必须是场景坐标这样后续生成图元时才不需要再做一次换算。update()触发的是整个 view 的重绘drawForeground中会根据这两个点画出临时矩形。这个流程能跑通还依赖两个容易被忽略的设置。一是setMouseTracking(true)否则鼠标键没有按下时 view 根本不会收到 move 事件但注意按下键期间 move 事件照常发送所以是否开启追踪的影响不大。二是setDragMode(QGraphicsView::NoDrag)这是默认值如果之前为了拖动画布设置了ScrollHandDrag按下鼠标后会触发视图滚动矩形绘制直接被框架吞掉。这两个参数在任何绘制模式下都建议显式设置一次。3. 两条可复现的绘制路径视图橡皮筋与场景动态图元坐标和事件链路打通之后剩下的问题就是矩形画在哪里、什么时候生成正式图元。这个问题有两条成熟路线一条是传统的橡皮筋画法用QPainter在视图前景层画临时矩形松开鼠标时再创建QGraphicsRectItem另一条是直接在场景里动态维护一个QGraphicsRectItem拖动时不断修改它的rect()。两条路都能用但适用场景不同。3.1 路径 A在视图层用 QPainter 画橡皮筋预览松开时生成 QGraphicsRectItem这是最正统的做法。橡皮筋只在预览阶段存在不进入场景因此不会干扰场景中的命中测试和图元计数。具体实现是重写drawForeground它绘制在场景坐标空间里天然跟随视图的缩放和平移。void DrawRectView::drawForeground(QPainter *painter, const QRectF rect) { Q_UNUSED(rect); if (!m_drawing) { return; } QPen pen(QColor(0, 120, 215), 1); pen.setCosmetic(true); // 线宽不随视图缩放变化 painter-setPen(pen); painter-setBrush(Qt::NoBrush); painter-drawRect(QRectF(m_sceneStartPos, m_sceneCurrentPos).normalized()); } void DrawRectView::commitRect() { QRectF rect QRectF(m_sceneStartPos, m_sceneCurrentPos).normalized(); if (rect.width() 1.0 || rect.height() 1.0) { return; // 过滤误触产生的零尺寸矩形 } auto *item new QGraphicsRectItem(rect); QPen pen(QColor(0, 120, 215), 1); pen.setCosmetic(true); item-setPen(pen); scene()-addItem(item); }参数说明pen.setCosmetic(true)是关键参数。默认情况下画笔宽度会随视图缩放倍率同步放大放大 4 倍后 1 像素的线看起来像 4 像素标注类工具里这是不可接受的。cosmetic 画笔保证线宽在屏幕上始终一致。normalized()解决了从右下往左上拖拽时矩形宽高为负的问题它会把QRectF调整成左上角在起点、右下角在终点的正矩形。为什么把临时矩形画在drawForeground而不是paintEvent因为drawForeground的 painter 已经处于场景坐标系直接使用两个场景坐标点即可而paintEvent里的 painter 是 viewport 坐标系需要先把场景坐标再映射回屏幕像素多一层换算且滚动时会不一致。这条路径适合需要精确控制预览样式、预览和数据分离的场景比如截图标注工具。3.2 路径 B用 QGraphicsRectItem 动态 setRect省掉橡皮筋代码如果你想少写一个重写函数可以换一种思路按下时直接创建一个QGraphicsRectItem放进场景移动时不断修改它的矩形。预览和最终结果共用同一个图元省去了绘制橡皮筋、再提交新图元的切换。void DrawRectView::mousePressEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { m_startPos mapToScene(event-pos()); m_tempItem new QGraphicsRectItem(); QPen pen(QColor(0, 120, 215), 1, Qt::DashLine); pen.setCosmetic(true); m_tempItem-setPen(pen); m_tempItem-setBrush(Qt::NoBrush); m_tempItem-setZValue(1000); // 置顶显示预览 scene()-addItem(m_tempItem); } QGraphicsView::mousePressEvent(event); } void DrawRectView::mouseMoveEvent(QMouseEvent *event) { if (m_tempItem) { QPointF curPos mapToScene(event-pos()); m_tempItem-setRect(QRectF(m_startPos, curPos).normalized()); } QGraphicsView::mouseMoveEvent(event); } void DrawRectView::mouseReleaseEvent(QMouseEvent *event) { if (m_tempItem event-button() Qt::LeftButton) { QRectF finalRect m_tempItem-rect(); if (finalRect.width() 1.0 || finalRect.height() 1.0) { scene()-removeItem(m_tempItem); delete m_tempItem; } else { m_tempItem-setPen(QPen(QColor(0, 120, 215), 1, Qt::SolidLine)); } m_tempItem nullptr; } QGraphicsView::mouseReleaseEvent(event); }参数说明setZValue(1000)保证预览矩形压在已有图元上方否则框选时临时矩形会被其他图元遮挡。虚线笔在预览阶段和实线笔在最终阶段使用同一支笔的两种风格切换是标注工具里常见的视觉反馈手法。这条路径的优点是代码量少预览和结果天然一致缺点也很明显临时图元进入了场景如果场景中已有大量图元命中测试会多算一个对象。另一个隐蔽问题是如果后续给图元设置了setPos()那么setRect()的值就必须转成 item 本地坐标。上面这段代码回避了这个问题因为图元没有设置pos()本地坐标等于场景坐标。两条路径的取舍我一般这么定需要高复用、预览样式复杂、将来可能把预览做成不同形状的画到场景外的选路径 A追求最小实现、只画矩形、不希望维护太多绘制代码的选路径 B。大多数标注需求用路径 B 就足够了它在交互反馈上更跟手。4. 避坑画矩形最常见的五个翻车现场与修复方式交互代码的毛病往往很隐蔽不是编译不过而是运行时表现诡异。下面这五个问题是我见过和踩过频率最高的按现象到原因再到解决的方式记录遇到类似情况可以直接对照。4.1 坐标错位与线宽变形两个一眼就能看出的现场坑一矩形没有出现在鼠标正下方而是偏移一段距离。现象是按下鼠标后画出的矩形位置整体偏右下方窗口滚动或缩放后偏移量还会变化。原因是setRect()直接用了event-pos()的 viewport 坐标而QGraphicsRectItem期望的是场景坐标。只要 view 滚动过viewport 原点就不再是场景原点两者数值差就是滚动偏移量。解决方法是所有用于绘制的坐标统一从mapToScene(event-pos())获取不要在绘制链路的任何一环混入 viewport 坐标。坑二视图放大后矩形边框变得粗得吓人。现象是场景放大若干倍后矩形边框线条粗到盖住了内部填充区域缩小后又细得看不清。原因是 Qt 的QPen默认线宽是“世界坐标宽度”会随视图缩放倍率同步变化。要修一行代码足够QPen pen(QColor(0, 120, 215), 1); pen.setCosmetic(true); item-setPen(pen);参数说明setCosmetic(true)把画笔标记为装饰性画笔线宽始终以屏幕像素计算不受视图缩放影响。如果你希望边框粗细跟随缩放刻意模拟手绘效果那就不要设置这个参数。普通标注、测量场景下建议一律开启。4.2 负宽高、丢事件与拖影三个藏着掖着的隐蔽坑坑三从右下往左上拖矩形直接消失或方向错乱。现象是只在某些拖拽方向能画出矩形。原因是从右下角往左上角拖动时QRectF(start, current)的宽高变成负数矩形区域反转甚至不渲染。解决方法是统一在提交前调用rect.normalized()它会把负宽高修正为正宽高并把左上角调整到正确的坐标位置。同时过滤掉宽或高小于 1 像素的误触QRectF rect QRectF(m_startPos, curPos).normalized(); if (rect.width() 1.0 || rect.height() 1.0) { return; }坑四鼠标拖得稍微快一点松开时矩形没有生成。现象是拖动过程中矩形还在预览一旦光标移出 view 再松开预览消失且场景里没有新图元。原因是松开事件发给了光标下的其他窗口view 根本没收到mouseReleaseEvent。常见做法是在按下时抓取鼠标// mousePressEvent 中 viewport()-grabMouse(); // mouseReleaseEvent 中 viewport()-releaseMouse();参数说明grabMouse()让 viewport 在鼠标按键释放前独占接收所有鼠标事件哪怕光标跑到窗口外部release 事件也会发回来。这里容易犯的错是只抓不放——releaseMouse()没调用后续鼠标点击全部失灵表现为“只能画一次矩形”这是这个坑最常见的翻车方式。注意抓取前先判断是否已经在绘制状态避免重复抓取。坑五拖动时橡皮筋闪烁松开后屏幕残留拖影。现象是移动过程画面闪烁或者松开后旧的预览内容还残留一小块。原因是每次 move 事件里更新区域太小或者使用了立即重绘函数导致新旧预览交替时出现撕裂。解决方法是让预览更新统一走update()配合setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate)缩小重绘范围setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate);这个参数告诉视图只重绘内容发生变化的区域而不是整帧刷新。如果你的场景图元很多预览闪烁又特别明显可以临时切换到FullViewportUpdate对比一下是重绘区域的问题还是绘制逻辑的问题。5. 让矩形可选中、可拖拽、可缩放图元交互的完整补全矩形画出来只是第一步真实工具里用户还得能移动它、改尺寸、删掉画错的。QGraphicsRectItem本身不自带缩放手柄但通过 Flags 和自定义子类可以很干净地补全这套交互。5.1 用 ItemFlags 开启选中与移动几行代码让图元活起来QGraphicsItem默认是不可选中、不可移动的。要让刚画出的矩形能被鼠标拖动需要设置 Flags。最常用的组合是选中、移动、聚焦三项auto *item new QGraphicsRectItem(QRectF(0, 0, 200, 100)); item-setFlags(QGraphicsItem::ItemIsSelectable | QGraphicsItem::ItemIsMovable | QGraphicsItem::ItemIsFocusable); item-setBrush(QBrush(QColor(0, 120, 215, 40))); item-setPen(QPen(QColor(0, 120, 215), 1)); scene()-addItem(item);参数说明ItemIsSelectable让鼠标点击能选中图元配合scene()-selectedItems()可以做批量操作ItemIsMovable开启拖拽移动按下后拖动图元的位置会被setPos()更新ItemIsFocusable让图元能接收键盘事件为后续 Delete 键删除图元做准备。半透明画刷是拖拽时观察位置的好帮手纯色画刷会挡住底图。一个容易被忽视的细节是画矩形时用的是虚线笔改成最终状态时换成实线笔这只是样式问题真正影响体验的是选中态的可视化。QGraphicsRectItem自带一个简单的选中框但视觉很弱建议在子类里根据isSelected()改变画笔颜色或加粗线宽让用户一眼看到当前操作对象。5.2 继承 QGraphicsRectItem 实现尺寸调整手柄支持拖边缘改大小QGraphicsRectItem没有内置的 resize 手柄需要自己实现。常见做法是继承它在鼠标事件里判断点击位置是否落在右边缘、下边缘或右下角命中后把拖拽位移加到矩形尺寸上。class ResizableRectItem : public QGraphicsRectItem { public: enum Edge { None 0, Right 1, Bottom 2, RightBottom 3 }; explicit ResizableRectItem(const QRectF rect) : QGraphicsRectItem(rect) { setFlags(ItemIsSelectable | ItemIsMovable); setAcceptHoverEvents(true); setBrush(QBrush(QColor(0, 120, 215, 40))); setPen(QPen(QColor(0, 120, 215), 1)); } protected: void hoverMoveEvent(QGraphicsSceneHoverEvent *event) override { setCursor(cursorForPos(event-pos())); QGraphicsRectItem::hoverMoveEvent(event); } void mousePressEvent(QGraphicsSceneMouseEvent *event) override { m_edge edgeForPos(event-pos()); m_startRect rect(); m_startScenePos event-scenePos(); if (m_edge None) { QGraphicsRectItem::mousePressEvent(event); } } void mouseMoveEvent(QGraphicsSceneMouseEvent *event) override { if (m_edge ! None) { QPointF delta event-scenePos() - m_startScenePos; QRectF r m_startRect; if (m_edge Right) { r.setRight(m_startRect.right() delta.x()); } if (m_edge Bottom) { r.setBottom(m_startRect.bottom() delta.y()); } setRect(r.normalized()); update(); } else { QGraphicsRectItem::mouseMoveEvent(event); } } void mouseReleaseEvent(QGraphicsSceneMouseEvent *event) override { m_edge None; QGraphicsRectItem::mouseReleaseEvent(event); } private: Edge edgeForPos(const QPointF pos) const { const qreal handle 8.0; QRectF r rect(); bool onRight qAbs(pos.x() - r.right()) handle; bool onBottom qAbs(pos.y() - r.bottom()) handle; if (onRight onBottom) return RightBottom; if (onRight) return Right; if (onBottom) return Bottom; return None; } QCursor cursorForPos(const QPointF pos) const { switch (edgeForPos(pos)) { case RightBottom: return QCursor(Qt::SizeFDiagCursor); case Right: return QCursor(Qt::SizeHorCursor); case Bottom: return QCursor(Qt::SizeVerCursor); default: return QCursor(Qt::ArrowCursor); } } Edge m_edge None; QRectF m_startRect; QPointF m_startScenePos; };参数说明handle 8.0是鼠标命中热区的半径单位是本地坐标数值太小时用户会很难点到边缘。delta用的是本次拖拽相对按下点的累计位移而不是计算每两次 move 之间的差值这样每帧都基于原始矩形计算不会因事件频率不均导致尺寸抖动。如果视图发生过缩放event-pos()与event-scenePos()会不同这里直接用scenePos做差值默认图元无变换时是等价的有变换时需要把 scene 坐标mapFromScene回本地坐标再计算。6. 验证与进阶用 QTest 锁住绘制逻辑用索引策略扛住大数据量交互代码写完后最容易被忽略的是自动化验证。很多人觉得鼠标拖动这类行为没法测其实 Qt 的QTest模块提供了完整的鼠标事件模拟 API可以让测试代码真实地走一遍按下、移动、松开的全流程然后断言场景里最终矩形的位置和尺寸。void testDrawByMouse() { DrawRectView view; view.setScene(new QGraphicsScene); view.resize(400, 300); view.show(); QVERIFY(QTest::qWaitForWindowExposed(view)); QTest::mousePress(view.viewport(), Qt::LeftButton, Qt::NoModifier, QPoint(50, 60)); QTest::mouseMove(view.viewport(), QPoint(150, 120)); QTest::mouseRelease(view.viewport(), Qt::LeftButton, Qt::NoModifier, QPoint(150, 120)); auto rectItems view.scene()-items(); QCOMPARE(rectItems.size(), 1); auto *rectItem dynamic_castQGraphicsRectItem *(rectItems.first()); QVERIFY(rectItem ! nullptr); QCOMPARE(rectItem-rect(), QRectF(50, 60, 100, 60)); }参数说明事件坐标是 viewport 坐标这就逼着测试用例和真实用户操作站在同一视角一旦生产代码里混用了坐标空间测试会直接失败。qWaitForWindowExposed是必须的窗口未显示时事件分发路径和显示后不同跳过它容易得到假阳性结果。这个最小测试用例建议在每次改动坐标转换逻辑时先跑一遍省的后面手动拖半天鼠标才发现回归。如果场景中的矩形数量上了几千甚至上万命中测试和重绘会明显变慢。这时把场景索引切到 BSP 树是性价比最高的一步scene-setItemIndexMethod(QGraphicsScene::BspTreeIndex);这个参数让场景按空间分块索引图元命中测试时只检查鼠标位置附近的小块。它适合图元分布稀疏、位置相对固定的场景如果矩形每帧都在被拖动BSP 树重建的开销可能超过收益需要实测对比。再往后走更彻底的做法是把矩形数据起点、宽高、样式与图元分离存储图元只作为视图层需要时从数据重建。我曾经为了省事跳过这类测试后来一次坐标换算改动把整个标注工具搞坏排查了很久才发现是把 viewport 坐标传进了图元。从那以后每次添加新的绘制模式我一定先把这个最小鼠标测试跑一遍再继续写功能。希望帮到你。本文还有配套的精品资源点击获取