★ FEATURED ARTICLE 用 pyqtgraph 画流程图我第一次听到这个需求时也觉得有点绕——毕竟在大多数人的认知里pyqtgraph 是画折线图、频谱图、图像的工具和流程图这种带节点的交互编辑器看起来是两条路。但实际折腾完一轮之后我的结论变了如果你要的不是“画一张静态流程图”而是一块能拖节点、能连线、能在操作中实时刷新的流程画布pyqtgraph 反而比 Qt 自带的 Graphics View 更快出活。这篇文章就记录一下我用 PyQt5 pyqtgraph 从零搭节点式流程图编辑器的完整思路包括自定义节点、端口连线、坐标换算、事件拦截以及我踩过的几个有点隐蔽的坑。适合正在做数据流展示、节点编辑、逻辑编排类桌面工具的人参考。1. 为什么我用 pyqtgraph 画流程图而不是 Qt 原生 Graphics View1.1 先说结论这不是误入歧途而是省掉一整套画布轮子很多人听到“流程图”三个字第一反应就是 QGraphicsScene QGraphicsView甚至有人会劝你别在 pyqtgraph 上硬蹭。我最早也是这么想的直到我在一个模拟项目里需要画布支持滚轮缩放、鼠标拖拽平移、外加大量动态节点才意识到 Qt 原生这套东西“能用”和“好用”之间差了整整一层体力活原生 Graphics View 默认不帮你做滚轮缩放需要自己监听 wheelEvent还要维护缩放锚点平移画布要么改 scrollbars要么自己写 drag mode抗锯齿、坐标变换、局部重绘这些细节都要自己处理。而 pyqtgraph 本身就是架在 Qt Graphics View 之上的高性能绘图框架它内嵌的 ViewBox 已经把平移、缩放、坐标映射处理得很完善。你专注的只是“画什么”而不是“画布怎么动”。1.2 数据可视化框架怎么承载节点编辑器理解这个方案的关键是意识到 pyqtgraph 的绘图模型和流程图天然同构。pyqtgraph 的常规用法是往 ViewBox 里塞 PlotDataItem、ImageItem 这类现成组件它们本质上是 scene 里的一个个 item。流程图里的一个节点不过也是一种自定义 item两个节点之间的一条连线也不过是另一种自定义 item。两者在 pyqtgraph 里共享同一套场景坐标、同一套鼠标事件、同一套重绘机制。换句话说画折线图是把一串数据点变成一个 PlotDataItem 丢进 ViewBox画流程图是把自己写的 NodeItem、EdgeItem 丢进 ViewBox。数据可视化框架和节点编辑器之间的差距没有看起来那么大。我在实际项目中通常直接使用 GraphicsView ViewBox而不是 GraphicsWindow因为后者会额外包一层窗口控制对纯嵌入式画布来说是多余的。一个干净的 ViewBox 加进去剩下的全是 item 逻辑。1.3 和 Qt 原生 Graphics View 的取舍对比这里有一份我实际对比后的结论不一定适合所有场景但至少代表了一个比较务实的判断维度对比维度PyQt5 pyqtgraphQt 原生 Graphics View画布平移缩放内置 ViewBox开箱即用需要手写 wheelEvent 与拖拽逻辑抗锯齿与渲染默认处理好可全局开关需要自行设置 RenderHint自定义图形节点继承 GraphicsObject 即可继承 QGraphicsItem局部重绘与裁剪paint 自带 bounds 参数方便裁剪需要自己管理 update 范围现成可用组件绘图组件丰富控件丰富但绘图组件少学习门槛文档偏少需要翻源码资料多但写法偏繁琐如果只是静态展示一张流程图这俩方案差别不大。但一旦牵扯到“拖节点、连边、实时刷新”这种交互pyqtgraph 的 ViewBox 帮你省掉的时间非常可观。我之前有个数据流展示工具几百个动态节点要跟着上游数据实时刷新位置用 pyqtgraph 两周就完成了主体其中大部分时间花在连线交互上而不是画布机制。1.4 什么时候不该用 pyqtgraph也别把 pyqtgraph 吹成万能的。如果你的目标是一个功能完整的专业流程图软件需要自动布局、锚点吸附、曲线编辑、多选框选、撤销重做建议老实回去用 Qt 原生 Graphics View 或者成熟的图编辑框架。pyqtgraph 适合的是“画布交互够用、节点数量可观、开发速度优先”的场景比如数据流可视化、参数编排面板、轻量级逻辑编辑器。我自己后续做的几个小工具也基本都是这个定位。2. 先搞清楚 pyqtgraph 的 item 体系再写 NodeItem 才不会踩坑2.1 工作区与积木的关系在 pyqtgraph 里最核心的坐标容器是 ViewBox它内部挂着一个 QGraphicsScene。所有画上去的东西都叫 item包括普通图形、数据曲线、图片以及你自定义的节点。一个常见的误解是自定义节点需要自己手动加入 scene然后还要管 scene 的坐标。实际上你要做的只是把自定义 item 通过 view_box.addItem(item) 丢进去。ViewBox 会帮你管理场景坐标、缩放变换、鼠标事件分派。所以我的编码习惯是把所有自定义 item 的本地坐标原点定在自身左上角这样移动节点时直接 setPos(x, y)不用关心 scene 坐标换算。这个约定在后面处理连线锚点时会省很多事。2.2 GraphicsObject 的 paint 和 boundingRect 怎么写这是 pyqtgraph 初学者最容易写错的地方。自定义 item 继承 pg.GraphicsObject 之后需要实现两个方法boundingRect()返回该 item 在自身本地坐标系里的边界paint(bounds, painter, widget)执行实际绘制。需要注意GraphicsObject.paint 的第一个参数不是 QStyleOptionGraphicsItem而是 pyqtgraph 已经帮你算好的可视范围 bounds你用不用都没关系。如果你愿意可以在 paint 开头做一次快速裁剪判断只有和 bounds 相交时才真正绘制。这个机制在处理几百个节点时非常有用但画节点这种小数量场景通常直接画就行。boundingRect 还有一个容易翻车的地方很多人习惯返回 QRectF(0, 0, w, h)但如果你在 paint 里画了矩形边框边框宽度会导致边缘像素被裁剪。我的做法是给 boundingRect 加一圈 padding比如 .adjusted(-4, -4, 4, 4)保证边框和阴影都不会被截断。2.3 为什么事件写鼠标点击反而没反应这是我从 Qt 原生转 pyqtgraph 时踩得最狠的一个坑。写惯了 QGraphicsItem 的人上手就会在自定义 item 里重写 mousePressEvent、mouseMoveEvent然后在 pyqtgraph 里发现事件根本不触发。原因pyqtgraph 的 GraphicsObject 把鼠标事件封装成了 mouseClickEvent 和 mouseDragEvent。它内部有一套自己的事件分发逻辑你不需要、也不应该按 QGraphicsItem 那套逻辑去重写原生的鼠标事件。更关键的是在这两个事件处理函数里你必须调用 event.accept()否则事件会被认为无人处理继续向 ViewBox 传播导致你拖节点的时候画布跟着平移、点端口的时候没有任何反应。这套事件模型是整个交互的基础我建议所有用 pyqtgraph 做编辑器的人第一步先写一个最基本的可拖动矩形把 mouseDragEvent 和 accept 搞明白再往下做节点和连线。3. NodeItem 实现可拖拽、可缩放、带端口的三要素3.1 节点绘制的最小要素一个流程图节点最基本的视觉要素有三样外框矩形、标题文本、端口圆点。外框我用圆角矩形标题放在上部输入端口放在左侧输出端口放在右侧。端口不一定非得是独立的 QGraphicsItem最开始实现时完全可以用一个数据结构去描述它在节点本地坐标系里的位置然后在节点的 paint 里统一画出来。端口坐标的约定很重要。假设节点宽度 W高度 H输入端口固定在 (0, H/2)输出端口固定在 (W, H/2)。后续任何连线操作都从这个本地坐标出发换算到场景坐标。3.2 完整 NodeItem 代码骨架先给一个可以直接跑的最小版本import pyqtgraph as pg from PyQt5 import QtCore, QtGui, QtWidgets class NodeItem(pg.GraphicsObject): def __init__(self, text, width120, height60): super().__init__() self.text text self.w width self.h height self.input_port (0, height // 2) self.output_port (width, height // 2) self.setFlag(self.ItemIsSelectable) self.setAcceptedMouseButtons(QtCore.Qt.MouseButton.LeftButton) self.setZValue(1) def boundingRect(self): return QtCore.QRectF(0, 0, self.w, self.h).adjusted(-4, -4, 4, 4) def paint(self, bounds, painter, widgetNone): painter.setRenderHint(QtGui.QPainter.RenderHint.Antialiasing) rect QtCore.QRectF(0, 0, self.w, self.h) painter.setBrush(QtGui.QColor(#2d2d2d)) painter.setPen(QtGui.QPen(QtGui.QColor(#aaaaaa), 1.5)) painter.drawRoundedRect(rect, 8, 8) painter.setPen(QtGui.QColor(#eeeeee)) painter.drawText(rect.adjusted(8, 4, -8, -4), QtCore.Qt.AlignmentFlag.AlignCenter, self.text) for p in (self.input_port, self.output_port): painter.setBrush(QtGui.QColor(#4a90d9)) painter.setPen(QtCore.Qt.PenStyle.NoPen) painter.drawEllipse(QtCore.QPointF(*p), 5, 5) def mouseDragEvent(self, event): if event.button() QtCore.Qt.MouseButton.LeftButton: event.accept() self.setPos(self.pos() event.pos() - event.lastPos())这段代码里有两个细节值得说。第一paint 里用了 painter.drawText 画文本虽然简单但文本长度超出节点宽度时需要自己处理实际项目中我会在外部切掉过长文字或者根据文本长度自适应宽度。第二mouseDragEvent 里用的是 event.pos() - event.lastPos()这是 pyqtgraph 封装的相对位移写法比拿全局坐标换算要可靠得多。3.3 端口坐标怎么暴露给连线用节点画完之后下一步是让外部能拿到端口的场景坐标。我的做法是在 NodeItem 上提供一个方法def port_scene_pos(self, is_inputTrue): port self.input_port if is_input else self.output_port return self.mapToScene(QtCore.QPointF(*port))mapToScene 是 QGraphicsItem 自带的能力它会考虑 item 自身的 setPos、缩放、旋转返回的是 scene 坐标。这条换算链路是整个连线系统的基础后面写 EdgeItem 时需要反复用到。3.4 拖拽时的 z 值管理节点多了以后拖到上层的节点应该盖住下面的节点。我的做法是在 mouseDragEvent 开始阶段把 z 值提高到 100释放后恢复回 1。pyqtgraph 里直接 setZValue 会触发重绘不会有闪烁问题。还要注意一点节点移动后一定要让与之相连的边刷新这一点放到第四部分说。4. 连线的本质一个跟随端点实时刷新坐标的 EdgeItem4.1 为什么连线也应该是一个 item很多人会把“连线”当成一组保存在数据结构里的坐标点然后在 ViewBox 的整个 scene 上统一绘制。这样做不是不行但只要节点一移动你就得手动管理整张画布的重绘坐标关系很容易乱。我把每条连线本身实现成一个独立 item和节点一样丢进 ViewBox。这样做有三个好处一是连线有自己的 z 值可以被节点盖住或者反过来二是可以单独对某条边调用 update() 刷新不用碰整个 scene三是删除一条边就是 removeItem 从列表里移除逻辑非常自然。4.2 坐标换算的正确姿势EdgeItem 的代码核心是 paint。我建议 EdgeItem 自身永远不调用 setPos也就是保持它在场景坐标原点。这样 EdgeItem 的本地坐标等于 scene 坐标在没有缩放的前提下画线时直接用场景坐标画即可。连线两端坐标通过节点的 port_scene_pos 换算class EdgeItem(pg.GraphicsObject): def __init__(self, src_node, dst_node): super().__init__() self.src_node src_node self.dst_node dst_node self.setZValue(0) self._path None def boundingRect(self): # 返回包含两个端点的矩形稍微放宽边界 s self.src_node.port_scene_pos(False) d self.dst_node.port_scene_pos(True) rect QtCore.QRectF(s, d).normalized().adjusted(-8, -8, 8, 8) return rect def _build_path(self): s self.src_node.port_scene_pos(False) d self.dst_node.port_scene_pos(True) path QtGui.QPainterPath(s) cx max(40, abs(d.x() - s.x()) / 2) path.cubicTo(s.x() cx, s.y(), d.x() - cx, d.y(), d.x(), d.y()) return path def paint(self, bounds, painter, widgetNone): painter.setRenderHint(QtGui.QPainter.RenderHint.Antialiasing) pen QtGui.QPen(QtGui.QColor(#888888), 2) painter.setPen(pen) painter.drawPath(self._build_path())这里我画的是三段式贝塞尔曲线也就是从一个端口水平延伸出一段再弯到另一个端口。控制点距离取两端点水平距离的一半至少 40 像素。这样画出来的线在有向连线里比直线好看而且不会在节点折弯处产生刺眼角度。4.3 为什么贝塞尔曲线这么画不会穿帮说起来有个小细节两个节点之间的距离非常近时如果控制点也取水平距离的一半曲线会变成一个别扭的“S”形。我加了一个 max(40, ...) 的下限就是为了避免这种情况。40 这个数值不是拍脑袋定的它大致等于一个端口圆点的直径加一点余量保证曲线在最近距离下也不会扭曲。4.4 动态刷新策略节点拖拽过程中EdgeItem 必须跟着刷新。我的做法是在节点 mouseDragEvent 的 setPos 之后主动遍历所有和这个节点相连的边调用 edge.update()。这里有一个性能上的选择问题是每次 setPos 都立刻重建 path还是只在 paint 时临时计算实测下来paint 里临时计算 path 在节点数量少时完全没问题几十条边可以忽略不计。但当边数量超过一两百条后每次拖动都触发大量贝塞尔计算和抗锯齿绘制会明显掉帧。我的优化手段是在 EdgeItem 里缓存 path并加一个 dirty 标记def mark_dirty(self): self._path None self.update() def _build_path(self): if self._path is None: # 构造并缓存 pass return self._path拖动节点时调用 mark_dirty不拖动的时候保留缓存。这样 paint 里绘制的是缓存 path而不是每次从零算。5. 完整 Demo可创建连线、可删节点的流程图画布5.1 主窗体和 ViewBox 配置一个可交互的流程图画布主窗体其实非常薄。我用 QGraphicsView 作为承载把 ViewBox 放进去关掉系统菜单和滚动条设置深色背景class FlowCanvas(pg.GraphicsView): def __init__(self): super().__init__() self.vb pg.ViewBox() self.setCentralItem(self.vb) self.vb.setBackgroundColor(#1e1e1e) self.vb.setMenuEnabled(False) self.vb.setMouseEnabled(xTrue, yTrue) self.nodes [] self.edges []setMenuEnabled(False) 很重要否则右键会弹出 pyqtgraph 自带的 view 菜单干扰你自己的右键删除逻辑。setMouseEnabled 保持默认双轴可平移缩放即可。5.2 创建连线的交互状态机连线交互我分成三个状态正常、按下端口、拖拽连线中。在 NodeItem 上增加一个端口被按下的判断逻辑当鼠标按下位置距离输入或输出端口小于一定半径时进入连线创建模式。用一个简单的状态标识位# 画布类中维护状态 self.state normal # normal / linking self.link_source None # 源端口信息 self.ghost_edge None # 临时连线鼠标一旦在节点端口附近按下就记录 source 节点和端口类型创建一个 ghost EdgeItem 并只设置终点为当前鼠标位置。Ghost 边用虚线画让用户看得清楚当前连到哪了。鼠标释放时如果落点附近存在另一个节点的合法端口就正式创建 EdgeItem否则移除 ghost。这里的判定规则要提前想清楚我的规则是“输出端口只能连输入端口且不能连自己”。判断鼠标是否落在端口上不能直接拿鼠标坐标去相等判断我给每个端口提供一个 hit 检测函数比较场景坐标距离是否小于阈值一般取 10~12 像素对应端口圆点半径加一点容差。5.3 右键删除节点及关联边删除节点必须把关联边一起清掉否则场景里会出现悬空线。最容易出错的是边列表的遍历方式你在遍历列表时直接 remove会导致索引错乱必须先把要删的边收集起来遍历结束后再统一删。def delete_node(self, node): removed [e for e in self.edges if e.src_node is node or e.dst_node is node] for e in removed: self.vb.removeItem(e) self.edges.remove(e) self.vb.removeItem(node) self.nodes.remove(node)右键菜单我直接用了 mouseClickEvent 里的右键判断。在 NodeItem 的 mouseClickEvent 里检查 event.button()如果是右键就发射一个 delete_requested 信号由画布容器统一处理删除。这里又要强调一次如果不调用 event.accept()右键事件会被 ViewBox 接走你的删除逻辑永远触发不了。6. 实测碰到的几个坑事件被抢、缩放线宽、绑定冲突6.1 拖节点时画布跟着平移问题出在哪这个坑是我接手过的几次项目里出现频率最高的。症状是鼠标按住节点拖动节点动一下画布也开始跟着平移。排查链路其实不复杂先确认 NodeItem 是否调用了 setAcceptedMouseButtons再确认 mouseDragEvent 里是否调用了 event.accept()最后确认你是不是意外在 paint 里返回了 False或者覆盖了默认的 mouseDragEvent。大部分情况都卡在第二点。pyqtgraph 的事件分派逻辑是item 不显式 accept事件就继续往上冒泡到 ViewBoxViewBox 一收到拖动事件自然就平移画布了。所以凡是涉及拖拽的自定义 item第一行就写 event.accept()。顺带提一个容易忽视的细节如果你在 mouseDragEvent 里做了复杂的逻辑判断提前 return 了也记得先 accept 再 return否则一样会冒泡。6.2 连线缩放后粗细怪异cosmetic pen 和整体缩放怎么选pyqtgraph 里 item 是跟随 ViewBox 一起缩放显示的。画节点矩形时缩放后整体变大会显得合理但画连线时如果 pen 宽度是固定的 2 像素放大时线宽会跟着变成很粗缩小时又细到看不见。两种处理方式一种是给连线使用 cosmetic penpen QtGui.QPen(QtGui.QColor(#888888), 1) pen.setCosmetic(True)设置 Cosmetic 之后无论画布怎么缩放线的屏幕宽度始终是 1 像素或你指定的像素值。这个方案适合连接线视觉上干净稳定。另一种方式是干脆接受整体缩放但给线宽做反变换处理。我实测下来流程图连线更适合 cosmetic pen因为连线不像节点那样需要保持文本可读它只是表示拓扑关系粗细恒定反而显得清爽。不过要注意cosmetic pen 在某些硬件加速环境下渲染性能比普通 pen 略差边数量很大时可以考虑关掉抗锯齿。6.3 同一环境装了多个 Qt 绑定时的冲突这是 PyQt5 pyqtgraph 使用中很容易忽略的坑。pyqtgraph 在 import 时会主动探测可用的 Qt 绑定不同版本的默认探测顺序不一样。如果机器上同时装了 PyQt5、PySide6pyqtgraph 可能加载到 PySide6导致你代码里从 PyQt5 导入的 QApplication 和 pyqtgraph 内部使用的绑定不一致程序在最开始就报错。解决办法是在 import pyqtgraph 之前强制指定绑定import os os.environ[PYQTGRAPH_QT_LIB] PyQt5 import pyqtgraph as pg我建议所有 PyQt5 项目都在入口文件最顶部设置这个环境变量哪怕当前环境很干净也设置一下。这个习惯能省掉很多“昨天还能跑今天换台机器跑不起来”的诡异问题。6.4 几百个节点时什么最影响性能最后说说性能。我把节点数压到 500 时发现瓶颈不在节点绘制而在边和抗锯齿。节点本身只是一个圆角矩形加两段文本几百个的绘制开销非常小边的贝塞尔曲线要经过 QPainterPath 的复杂曲线光栅化才是主要开销抗锯齿在曲线绘制上更贵但视觉上又不能完全关掉。我的折中方案是边数超过 150 条时将连线从贝塞尔切换成直线移动拖拽过程中用一个计时器做限频比如 30ms 聚合一次刷新而不是每次鼠标移动都立刻刷。这些优化做完后500 节点、400 条边的场景拖拽基本保持在流畅水平。6.5 一个容易忽略的细节prepareGeometryChange如果节点尺寸会在运行时变化比如文本变长了要改宽移动之前一定要调用 prepareGeometryChange()。这个方法是 QGraphicsItem 的底层通知机制告诉场景“我要换边界了”场景才能正确重建索引。直接改 boundingRect 而不通知会导致选中区域和点击命中区域错位这也是一个不太容易第一时间发现的问题。说实话这套方案第一次跑通的时候比我预想的顺利主要因为 pyqtgraph 把画布缩放和平移这两个最烦人的底层问题都处理好了。我再分享一个小建议做这类节点编辑器我都是先写删除逻辑、再写连线逻辑、最后才写拖拽逻辑。删除逻辑会逼你把边和节点的关系数据模型理清楚等到写连线和拖拽时很多结构问题已经被提前暴露出来了。动态数据流展示、参数配置面板、轻量逻辑编排这些场景用这套方案基本都能直接套用。别被“pyqtgraph 只能画图”的刻板印象限制住它的 item 体系本身就是为你干这类事情准备的。
阅读完成 · 觉得有帮助？
