简介一份面向 Qt 开发者的图形视图框架演示工程核心是使用 QGraphicsView 实现可滑动的窗体界面。工程以场景、视图、图形项三者协作作为主线将工具栏按钮、背景图片与多张内容页都设计成场景中的图形项完整呈现了滑动窗体的构建与组织方式同时展示了如何通过资源文件统一管理位图、矢量图、图标等素材适合想要深入理解 Qt 视图系统并动手仿写的初、中级开发者。资源共 25 个文件包含 11 张 jpg 位图、6 张 svg 矢量图和 4 张 png 图标另有 qrc 资源清单、cpp 源码、pro 工程配置和 txt 说明文档位图用于页面背景、svg 与 png 图标用于工具栏按钮压缩包仅 664KB结构简洁。目前已有 3306 人学习/下载。借助这套工程可以掌握场景中图形项的挂载与布局、滑动窗体的交互实现、图片资源的加载与组织方式还可以把示例中的素材替换为真实内容快速改造成相册浏览、产品展示或控制面板一类滑动界面其中多张食物主题图片也能帮助理解不同内容页的切换效果。1. 为什么用 QGraphicsView 做滑动窗体1.1 从一次实际需求说起去年做一个组态编辑器项目界面里要放几百个设备图元用户能拖动画布、缩放查看、点击选中。第一版图省事直接拿QScrollArea套一个QWidget图元全用QLabel和自绘paintEvent往上摆。结果一上线就翻车图元一多拖动滚动条明显掉帧缩放更别想——QScrollArea压根没有缩放这回事只能靠整体放大QWidget的字体和布局一放大全是马赛克。后来换成QGraphicsView重写整个体验直接上了个台阶。滑动窗体这个需求听起来像是“用滚动条看内容”但真正落到 Qt 里QGraphicsView才是干这个活的正主。它天生就是为“大量可交互图元 平移 缩放 选择”设计的底层用 BSP 树做索引绘制时只渲染视口内的 item性能比QScrollArea硬扛高出一个量级。1.2 滑动窗体的本质滑动窗体到底在滑什么拆开看就两件事内容超出视口后的平移浏览和内容密度过高时的缩放查看。QScrollArea解决前者但对后者无能为力QGraphicsView从架构上就把这两件事都包了。QGraphicsView的核心是经典的 Model/View 架构QGraphicsScene管理所有图元的“世界”相当于一个无限大的画布坐标系。QGraphicsItem画布上的一个个图元负责自己的绘制、碰撞检测、事件响应。QGraphicsView一个“窗口”你通过它看场景它负责把场景坐标映射到屏幕坐标并处理鼠标滚轮、拖拽、键盘事件。滑动窗体效果本质上就是在QGraphicsView里设置好场景范围sceneRect然后通过平移Scroll、缩放Scale、惯性滑动QScroller三个维度操作这个窗口。理解了这三者的关系就不容易写出“画布内容显示不全”“拖动看起来像位移但内容不动”“缩放后找不到焦点”这类问题了。1.3 适用范围和选型建议QGraphicsView做滑动窗体最适合这几类场景地图/瓦片图展示热词里也有人搜qgraphicsview 显示瓦片地图就是典型场景组态软件、流程图编辑器、电路图设计工具图片浏览器的缩放平移大数量卡片/节点的滑动选择器如果你的需求只是“一个纯文本页面太长要滚动看”那QScrollArea足够别杀鸡用牛刀。但只要内容里涉及“可交互的图形元素”“缩放”“图元数量动辄上百上千”直接选QGraphicsView省得后面推倒重来。我见过不少项目一开始用QScrollArea做到一半发现要加缩放和选中态最后全量重构的。2. 核心细节解析与实操要点2.1 理解 Scene、View、Item 的三角关系新手最容易栽的坑是把QGraphicsView当普通 Widget 用在上面直接布局然后发现坐标全乱。正确的姿势是所有内容都放 Scene 里View 只负责展示。好比你要看一幅巨大的画Scene手里拿了个放大镜View画上的人物花鸟Item都长在画布上放大镜里看到什么取决于你的手往哪儿举、镜片倍数多少。View 和 Item 之间永远隔着一层 Scene谁也别想绕过。对应到代码QGraphicsScene *scene new QGraphicsScene(this); scene-setSceneRect(-500, -500, 1000, 1000); // 画布范围 scene-addRect(-500, -500, 1000, 1000, QPen(Qt::gray)); // 背景范围示意 QGraphicsView *view new QGraphicsView(this); view-setScene(scene); view-setRenderHint(QPainter::Antialiasing); // 抗锯齿画曲线图形必开 view-setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate);sceneRect特别重要。它决定了场景的“边界”View 滚动条的取值范围、图元是否可见都跟它相关。如果不设Qt 会根据所有 Item 的边界自动计算但一旦 Item 动态增删这个范围会不断跳动滑动体验非常诡异。所以我的习惯是要么显式指定固定范围要么在 Item 增删后调用scene-setSceneRect(scene-itemsBoundingRect())手动刷新。2.2 滑动与惯性滑动的两种实现方案滑动窗体最核心的交互就是“拖动内容”。在QGraphicsView里有两种常见做法方案一QGraphicsView::ScrollHandDragview-setDragMode(QGraphicsView::ScrollHandDrag);设置之后鼠标左键拖拽就直接变成手型拖动画布不用写一行事件代码。这个方案做“拖动浏览”是最快的但有个坑一旦开启ScrollHandDragView 默认会拦截鼠标左键事件图元的mousePressEvent可能收不到。解决办法是重写 View 的mousePressEvent动态切换拖拽和点击模式。方案二QScroller惯性滑动如果你想要手机那种“松手后还继续滑一会儿再慢慢停”的惯性效果ScrollHandDrag就满足不了了。Qt 提供了QScroller可以直接给QGraphicsView加惯性QScroller::grabGesture(view-viewport(), QScroller::LeftMouseButtonGesture); QScrollerProperties sp QScroller::scroller(view-viewport())-scrollerProperties(); sp.setScrollMetric(QScrollerProperties::DecelerationFactor, 0.5); QScroller::scroller(view-viewport())-setScrollerProperties(sp);这里有几个参数值得说DecelerationFactor是减速因子数值越小滑得越远、停得越慢MinimumVelocity和MaximumVelocity控制触发惯性所需的最小速度和最大上限。实测下来把DecelerationFactor调到 0.5 左右手感接近微信图片浏览器的滑动0.9 以上基本是秒停适合列表类场景。注意QScroller只处理“滑动的手势”它不影响滚轮缩放。如果需要滚轮缩放还是要自己写wheelEvent。2.3 缩放与锚点别让视图“越缩越偏”滚轮缩放是滑动窗体体验分水岭。很多人直接把 View 的scale()放进wheelEvent里void MyView::wheelEvent(QWheelEvent *event) { qreal factor event-angleDelta().y() 0 ? 1.25 : 0.8; scale(factor, factor); }这段代码能跑但手感稀烂缩放时永远以视口左上角为固定点鼠标指着哪儿根本不重要。正确做法是让缩放以鼠标位置为锚点void MyView::wheelEvent(QWheelEvent *event) { QPointF anchor mapToScene(event-position().toPoint()); qreal factor event-angleDelta().y() 0 ? 1.25 : 0.8; setTransformationAnchor(QGraphicsView::AnchorUnderMouse); scale(factor, factor); // 缩放后修正避免锚点漂移 QPointF newAnchor mapToScene(event-position().toPoint()); QPointF delta newAnchor - anchor; translate(delta.x(), delta.y()); }这里有个容易忽略的点setTransformationAnchor(QGraphicsView::AnchorUnderMouse)本身会尝试保持鼠标下的点不动但连续多次缩放时由于浮点误差累积锚点还是会轻微漂移。所以更稳妥的写法是先拿到鼠标在 Scene 中的坐标缩放完再补偿一次偏移量。另外还有一个细节要限制缩放范围。不做上下限的话用户一通乱滚画布会被缩放到 0.001 倍或 1000 倍想找回原来的视图就很痛苦。qreal currentScale transform().m11(); if ((factor 1.0 currentScale 5.0) || (factor 1.0 currentScale 0.2)) return;2.4 Item 的边界框与绘制开销滑动窗体里的内容最终都是一个个 Item。Item 写得不好View 再高效也没用。两个核心点boundingRect()必须精确paint()必须轻量。boundingRect()返回的是 Item 的“外接矩形”。View 的可见性判断、碰撞检测都靠它。如果它的范围比实际绘制区域大会出现大片“透明区域也算命中”的情况点击选择时会莫名选不中或选错如果比实际绘制区域小会出现绘制内容被裁剪。paint()里建议不要做动态创建对象、字符串拼接、加载图片这类重操作。View 在滚动、缩放时会频繁调用paint()这些操作一旦出现性能直接崩。如果有经常变化的文本缓存成静态成员或一次性创建好。3. 实操过程与核心环节实现3.1 搭建一个可复用的滑动窗体基类直接贴一个我项目中抽出来的完整例子包含了滑动、惯性、缩放、坐标修正拿去就能跑。// SlideableView.h #pragma once #include QGraphicsView #include QScroller #include QScrollerProperties #include QWheelEvent #include QMouseEvent class SlideableView : public QGraphicsView { Q_OBJECT public: explicit SlideableView(QWidget *parent nullptr) : QGraphicsView(parent) { setRenderHint(QPainter::Antialiasing); setRenderHint(QPainter::SmoothPixmapTransform); setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate); setTransformationAnchor(QGraphicsView::AnchorUnderMouse); setResizeAnchor(QGraphicsView::AnchorViewCenter); // 惯性滑动 QScroller::grabGesture(viewport(), QScroller::LeftMouseButtonGesture); auto *scroller QScroller::scroller(viewport()); QScrollerProperties sp scroller-scrollerProperties(); sp.setScrollMetric(QScrollerProperties::DecelerationFactor, 0.5); sp.setScrollMetric(QScrollerProperties::MaximumVelocity, 0.8); scroller-setScrollerProperties(sp); } protected: void wheelEvent(QWheelEvent *event) override { QPointF anchor mapToScene(event-position().toPoint()); qreal factor event-angleDelta().y() 0 ? 1.25 : 0.8; // 限制缩放范围 qreal currentScale transform().m11(); if ((factor 1.0 currentScale 5.0) || (factor 1.0 currentScale 0.2)) return; scale(factor, factor); QPointF newAnchor mapToScene(event-position().toPoint()); QPointF delta newAnchor - anchor; translate(delta.x(), delta.y()); event-accept(); } };关键配置说下SmoothPixmapTransform缩放图片时用平滑插值否则图元边缘全是锯齿。代价是绘制慢一点如果 Item 数量特别大比如上千个可以视情况关掉。AnchorViewCenter窗口大小变化时以视图中心为锚点保持场景位置不变这个对布局稳定性很重要。BoundingRectViewportUpdate视口更新时只重绘变化的矩形区域比FullViewportUpdate省不少性能。但注意如果你 Item 之间有重叠可能需要用MinimalViewportUpdate或SmartViewportUpdate观察一下有无残影。3.2 给滑动窗体填充内容基类写好了往里放内容就简单了。以“卡片滑动选择器”为例场景里水平排列 10 张卡片每张卡片是自定义 Item用户能拖动浏览、滚轮缩放、点击卡片触发信号。// CardItem.h class CardItem : public QGraphicsObject { Q_OBJECT public: CardItem(const QRectF rect) : m_rect(rect) { setFlag(QGraphicsItem::ItemIsSelectable); setAcceptHoverEvents(true); } QRectF boundingRect() const override { return m_rect; } void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget) override { painter-setRenderHint(QPainter::Antialiasing); // 选中态 if (option-state QStyle::State_Selected) { painter-setBrush(QColor(70, 130, 180, 100)); painter-setPen(QPen(QColor(70, 130, 180), 2)); } else { painter-setBrush(QColor(255, 255, 255)); painter-setPen(QPen(QColor(180, 180, 180), 1)); } painter-drawRoundedRect(m_rect, 8, 8); // 文本 painter-setPen(Qt::black); painter-drawText(m_rect, Qt::AlignCenter, m_text); } private: QRectF m_rect; QString m_text QStringLiteral(卡片); };// main window setup QGraphicsScene *scene new QGraphicsScene(this); const int cardWidth 160; const int cardHeight 100; const int gap 20; for (int i 0; i 10; i) { CardItem *card new CardItem(QRectF(0, 0, cardWidth, cardHeight)); card-setPos(i * (cardWidth gap), 0); scene-addItem(card); } scene-setSceneRect(scene-itemsBoundingRect().adjusted(-50, -50, 50, 50)); view-setScene(scene); view-setMinimumSize(600, 400);scene-setSceneRect(scene-itemsBoundingRect())这行是动态计算场景范围的关键。它取了所有 Item 的外接矩形的并集再 expand 一圈保证场景边缘有一定留白。热词里有人搜“加载焊缝并选择提取焊缝”如果用这个框架做就是把焊缝轮廓线搞成自定义 Item点击时用QGraphicsScene::selectedItems()拿到选中的焊缝再走轮廓提取逻辑套路是一样的。3.3 坐标转换滑动窗体的核心功防滑动窗体最容易出 bug 的地方是坐标转换。思路其实就一句话事件里能用场景坐标就别用视图坐标能在地图坐标就别自己去算偏移。QGraphicsView提供了几个转换函数mapToScene(QPoint)视图坐标 → 场景坐标mapFromScene(QPointF)场景坐标 → 视图坐标mapToScene(QRect)、mapFromScene(QRectF)矩形版本鼠标点击选中的时候Item 拿到的event-pos()是 Item 坐标系要用mapToScene转成场景坐标再判断落在哪个图元上。QGraphicsScene::itemAt(pos, transform)可以快速拿到指定位置的顶层 Item比手动遍历所有 Item 高效得多。3.4 背景网格的实现做组态或地图类应用时通常会加一个背景网格方便对齐和定位。直接在drawBackground里画而不是塞一堆 Item这是性能提升的关键void SlideableView::drawBackground(QPainter *painter, const QRectF rect) { QGraphicsView::drawBackground(painter, rect); const int gridSize 50; QRectF sceneRect scene()-sceneRect(); painter-setPen(QPen(QColor(230, 230, 230), 0)); qreal left std::floor(rect.left() / gridSize) * gridSize; qreal top std::floor(rect.top() / gridSize) * gridSize; QVarLengthArrayQLineF, 100 lines; for (qreal x left; x rect.right(); x gridSize) lines.append(QLineF(x, rect.top(), x, rect.bottom())); for (qreal y top; y rect.bottom(); y gridSize) lines.append(QLineF(rect.left(), y, rect.right(), y)); painter-drawLines(lines.data(), lines.size()); }drawBackground是 View 的虚函数在绘制背景时自动调用。注意它是真正的“背景”不会被子 Item 覆盖后影响到 Item 的排序。网格线的绘制范围只用rect当前可见区域不要遍历整个场景范围否则场景大到一定程度性能又会劣化。4. 常见问题与排查技巧实录4.1 白屏啥都没显示没显示的原因九成出在 Scene 没关联或 Item 坐标超出可视范围。排查顺序确认view-setScene(scene)被调用过。在scene-addItem之后打印item-pos()和item-boundingRect()看坐标是否在sceneRect内。在view-show()后手动调view-fitInView(scene-itemsBoundingRect(), Qt::KeepAspectRatio)如果这时候能看到内容说明是初始视图没对准。另外一个隐蔽坑Item 的boundingRect()返回的是 Item 坐标系的矩形。如果 Item 设置了setPos(100, 100)那它在场景中的实际范围是pos() boundingRect()。新手常犯的错误是boundingRect()返回超大范围实际上内容只在很小一块区域里画导致看起来“白屏”但 View 已经显示了视觉上找不到内容。4.2 滑动时图元闪烁/残影闪烁通常跟viewportUpdateMode有关系。默认的MinimalViewportUpdate理论上重绘最少但在某些驱动上会有残影。我的经验是图元少用BoundingRectViewportUpdate图元多且频繁更新用SmartViewportUpdate或直接FullViewportUpdate。还有一种情况Item 的paint()里用了QPainter::save/restore但没配对或者用了非QBrush的填充方式导致绘制状态污染了相邻 Item视觉上就是闪烁和错乱。检查一下paint()里是否有悬挂的save()操作。4.3 滚轮缩放时内容“飘走”了内容飘走本质是锚点计算错误。我调试时发现在wheelEvent里用event-position()是 Qt5.14 之后的接口返回QPointF旧版用的event-pos()返回QPoint。如果混用了版本或者没取position()而取了老的pos()在某些高 DPI 缩放下坐标会偏内容就会越滚越偏。更稳妥的方案是直接重写wheelEvent时先event-position()转成QPointF再mapToScene不要自作聪明做 DPI 换算。4.4 点击 Item 但mousePressEvent不触发这种情况几乎都是被ScrollHandDrag或者QScroller吞掉了事件。ScrollHandDrag模式下左键拖拽被 View 接管Item 收不到。解决办法是重写 View 的mousePressEvent根据情况切换模式void SlideableView::mousePressEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { QGraphicsItem *item itemAt(event-pos()); if (item item-flags() QGraphicsItem::ItemIsSelectable) { setDragMode(QGraphicsView::NoDrag); } else { setDragMode(QGraphicsView::ScrollHandDrag); } } QGraphicsView::mousePressEvent(event); }这样点击到可选 Item 时进入普通模式Item 能正常处理事件点空白区域时进入拖拽模式滑动浏览。4.5 大量 Item 时滑动掉帧严重掉帧问题要分层排查Item 数量超过 5000 时优先检查是否所有 Item 都设置了合理的boundingRect。Item 太小小于 2-3 像素时BSP 树索引效率反而下降可以考虑用 Level of DetailsetFlag(QGraphicsItem::ItemIgnoresTransformations)或者根据缩放级别切换绘制细节。绘制开销把paint()里的耗时操作全部缓存。文本绘制drawText非常贵能预渲染成 QPixmap 就预渲染。update 频率如果业务上经常刷新 Item尽量合并刷新用scene-update()批量触发别一个个 Item 单独 update。我之前有个项目Item 里放了 5000 多个小方块每个方块绘制时都调painter-setBrush并 drawRect掉到 20 帧。优化方案是把同色方块合并成一个 Item用drawPoints或者drawLines批量绘制帧率直接翻到 60。5. 结尾再分享两个小技巧用 QGraphicsView 做滑动窗体方法和坑其实就那么几个。第一个技巧做地图/瓦片类应用时尽量不要往 Scene 里塞几百个图片 Item而是自己管理瓦片缓存在drawBackground里按当前视口动态绘制瓦片。热词里那条“qt使用qgraphicsview显示瓦片地图”就是这么干的直接放 Item 会卡到怀疑人生。第二个技巧滑动窗体里要支持拖拽排序或者框选时建议自己维护一个“选中集合”状态而不是每次都用scene-selectedItems()。后者在 item 数量大时会做一遍全场景遍历性能远不如维护局部队列。最后调试这类项目时多利用QGraphicsView自带的调试功能。设置环境变量QT_GRAPHICSVIEW_DEBUG1可以输出绘制区域和更新区域的信息定位闪烁问题特别有用。祝各位一次跑通少踩几个我踩过的坑。本文还有配套的精品资源点击获取