PySide6 流程图编辑器实战：从需求到上手指南（附代码结构解读）

PySide6 流程图编辑器实战：从需求到上手指南（附代码结构解读）

这是一篇面向「桌面端 GUI 初学者 / 个人开发者」的实践记录。项目已开源，支持拖拽放置图形、连线（直线/正交）、折点拖拽、属性面板、SVG/PNG 导出，并可一键打包为 EXE。本文带你了解功能、架构、关键实现与运行方式，方便直接上手或二次开发。

1. 项目背景与目标

• 定位：轻量级、离线可用的个人流程图工具，核心是“好用且可控”。
• 技术栈：PySide6（Qt for Python），QGraphicsView / QGraphicsScene 渲染。
• 交付物：源码 + 可运行 EXE + 博客说明 + 封面 SVG。

2. 功能清单（当前版本 v0.1.0）

• 画布：滚轮缩放、网格显示、网格吸附、对齐参考线。
• 图形：矩形、圆角矩形、菱形、文本。左侧 Shapes 面板拖拽放置。
• 连线：直线/正交两种模式，起点圆点 + 终点箭头；支持折点拖拽、线与线连接。
• 属性面板：节点/连线的颜色、线宽、文本、线型切换（Straight / Orthogonal）。
• 导出：扁平化 SVG，白底 PNG。
• 使用说明：右侧 Usage 面板内置快捷键与操作提示。
• 快捷键：V选择工具、C连线工具、Delete删除、Esc取消连线。

3. 代码架构总览

项目根目录（关键文件）：

app/ main.py # 入口，设置全局样式 & 启动主窗体 canvas/ # 画布与交互层 canvas_view.py # 视图：缩放/平移/拖拽/拖放放置图形 canvas_scene.py # 场景：网格绘制、对齐参考线 items/ # 图元定义 node_item.py # 节点：形状/锚点/文本 edge_item.py # 连线：直线/正交、箭头、圆点、折点 edge_handle_item.py # 折点拖拽手柄 ui/ # UI 布局与面板 main_window.py # 主窗体、菜单/工具栏、Dock 面板 shape_panel.py # 图形面板（拖拽放置） property_panel.py # 属性面板（颜色、线宽、文本、线型） help_panel.py # 使用说明面板 io/ # 导出 svg_exporter.py # 扁平化 SVG 导出 png_exporter.py # PNG 导出 model/ # 数据模型（后续 JSON 持久化预留） commands/ # 撤销/重做命令预留

设计思路：UI 与画布解耦；节点/连线独立成图元类；导出模块独立；数据模型预留，以便后续做 JSON 持久化和撤销栈。

4. 关键实现细节

4.1 图形与锚点

• NodeItem负责形状绘制与锚点计算。锚点放在四边中点，适当外移 1px，避免线压边。

4.2 连线与折点

• EdgeItem支持两种线型：straight（直线/斜线）与orthogonal（正交折线）。
• 起点圆点 + 终点箭头在paint()中绘制；折点通过EdgeHandleItem拖拽调整。
• 线可连接到节点，也可连接到另一条线（抽取路径最近点）。

4.3 对齐与吸附

• 网格吸附：拖动节点时自动吸附到网格点。
• 对齐参考线：当中心/边缘接近其他节点时，显示蓝色虚线并吸附。

4.4 拖拽放置

• ShapePanel通过QDrag + QMimeData传递节点类型；CanvasView.dropEvent创建并放置节点。

4.5 导出

• SVG：节点输出为 rect/polygon/text，连线输出 path + circle/polygon（箭头/圆点），完全扁平化，可二次编辑。
• PNG：scene.render()到QImage，默认白底。

5. 运行与打包

本地运行

python -m venv .venv .venv\Scripts\activate pipinstallpyside6 pillow python -m app.main

（Anaconda 环境同理，激活后直接安装依赖并运行。）

打包 EXE（PyInstaller）

D:\anaconda3\Library\bin\conda.bat run -n pyside_test python -m pipinstallpyinstaller pillow python -c"from PIL import Image;from pathlib import Path;src=Path('app.png');img=Image.open(src);img.save('app.ico', sizes=[(16,16),(24,24),(32,32),(48,48),(64,64),(128,128),(256,256)])"D:\anaconda3\Library\bin\conda.bat run -n pyside_test pyinstaller -F -w -n FlowchartEditor -i app.ico -p.app\main.py

产物位于dist/FlowchartEditor.exe。

6. 迭代计划（Roadmap 摘要）

• v0.2：JSON 保存/打开，最近文件，自动保存（可选）
• v0.3：更多图形库（UML/数据库/云服务），连线自动避障，主题样式
• v0.4：多画布/多页面，基础导入（draw.io/Visio 简化）

7. 适合谁？

• 想用 PySide6 练手完整桌面应用的初学者。
• 需要一个“可控、可改”的流程图工具做个人文档、汇报的工程师/产品。
• 想在此基础上扩展协作、模板、云存储的团队开发者。

8. 获取与使用建议

• 直接运行或打包后的 EXE 即可使用；默认界面即包含使用说明面板。
• 需要定制图形或样式，可在node_item.py/edge_item.py添加新的图元与主题。
• 计划做持久化时，可在model/补充 JSON 读写，并挂到菜单或快捷键。

如果你想进一步扩展（多人协作、在线版、模板库或主题切换），欢迎基于当前架构继续演进。希望这份项目能成为你学习 PySide6 的一条清晰路径。祝开发愉快！

9. 读者互动 & 获取源码

• 如果你在阅读、写作、整理资料过程中，需要定制其他小工具，欢迎在公众号「码海寻道」后台留言，我会尽量安排。
• 对工具细节或使用方式有任何问题，也欢迎留言交流。
• 获取源码：在公众号「码海寻道」后台回复“流程图”，即可获得项目源码链接。