这是一篇面向桌面端 GUI 初学者与个人开发者的实践记录。项目已开源，支持拖拽放置图形、连线（直线与正交两种模式）、折点拖拽、属性面板、SVG/PNG 导出，并可一键打包为 Windows 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. 代码架构总览
项目采用模块化设计，以清晰分离 UI、画布逻辑、图元和导出功能。以下是核心目录结构：
app/
main.py # 程序入口，负责设置全局样式并启动主窗体
canvas/ # 画布与交互核心层
canvas_view.py # 视图层：处理缩放、平移、拖拽、图形拖放放置
canvas_scene.py # 场景层：负责网格绘制、对齐参考线计算
items/ # 所有图形图元的定义
node_item.py # 节点图元：封装形状绘制、锚点计算与文本
edge_item.py # 连线图元：实现直线/正交、箭头/圆点绘制
edge_handle_item.py # 连线折点拖拽手柄
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 界面与底层画布逻辑解耦；将节点和连线定义为独立、可复用的图元类；导出功能独立成模块；同时预留了数据模型和命令栈，为未来实现项目文件保存和撤销重做打下良好基础。这种清晰的模块划分是构建可维护桌面应用的关键，你可以前往 云栈社区 的架构板块查看更多关于系统设计的讨论与实践。
4. 关键实现细节
4.1 图形与锚点
NodeItem 类封装了节点的全部逻辑，包括形状绘制和连接锚点的计算。锚点通常被定位在图形四边的中点，并向外微调1像素，以确保连线不会压在图形边框上，使视觉效果更清晰。
4.2 连线与折点
EdgeItem 支持两种线型：straight（直线或任意斜线）与 orthogonal（由水平和垂直线段构成的正交折线）。- 起点的圆点和终点的箭头均在图元的
paint() 方法中动态绘制；连线上的折点由独立的 EdgeHandleItem 图元表示，支持鼠标拖拽调整位置。
- 连线不仅可以连接到节点的锚点，还可以智能地连接到另一条连线上（算法会计算并抽取路径上的最近点）。
4.3 对齐与吸附
- 网格吸附：当用户拖动节点时，其位置会自动对齐到最近的网格交叉点，保证排版整齐。
- 对齐参考线：当一个节点的中心线或边缘在移动过程中接近其他节点的对应位置时，画布会显示蓝色的虚线作为视觉提示，并自动吸附对齐。
4.4 拖拽放置
ShapePanel（图形面板）利用 Qt 的 QDrag 和 QMimeData 机制来传递用户选择的节点类型。CanvasView（画布视图）在其 dropEvent 事件处理函数中接收该类型信息，并在鼠标释放位置创建对应的节点图元，完成放置动作。
4.5 导出功能
- SVG导出：将场景中的所有节点输出为标准的 SVG 元素（如
<rect>, <polygon>, <text>），连线输出为 <path> 并结合 <circle> 或 <polygon> 表示箭头和圆点。导出结果为完全扁平化的 SVG，可直接用矢量编辑软件（如 Inkscape、Illustrator）打开和修改。
- PNG导出：调用
scene.render() 方法将整个场景渲染到一个 QImage 上，然后保存为 PNG 图片，默认使用白色背景。
5. 运行与打包
5.1 本地运行（推荐使用虚拟环境）
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
pip install pyside6 pillow
python -m app.main
（如果你使用 Anaconda，操作同理：创建或激活对应环境后，安装依赖并运行主程序。）
5.2 打包为独立 EXE（使用 PyInstaller）
以下是在 Windows 系统下，使用 Anaconda 环境打包的示例命令：
D:\anaconda3\Library\bin\conda.bat run -n pyside_test python -m pip install pyinstaller pillow
# 将项目图标转换为 .ico 格式（假设存在 app.png）
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
打包完成后，可执行程序 FlowchartEditor.exe 将生成在 dist/ 目录下。
6. 迭代计划（Roadmap 摘要）
- v0.2：实现基于 JSON 格式的项目文件保存与打开功能，增加最近文件列表和可选的自动保存。
- v0.3：扩展图形库，加入更多预置形状（如 UML 图元、数据库表、云服务图标等）；实现连线自动避障功能；支持切换主题样式。
- v0.4：支持多画布或多页面管理；探索并实现基础的文件导入功能（如简化版的 draw.io 或 Visio 文件导入）。
7. 适合谁使用？
- PySide6 / Qt 初学者：希望通过对一个功能完整的桌面应用进行剖析与练手，来快速掌握其核心框架与开发模式。
- 有定制需求的工程师或产品经理：需要一款“完全可控、可按需修改”的轻量级流程图工具，用于绘制个人技术文档、架构图或汇报材料。
- 希望进行二次开发的团队：可以基于当前稳定、模块化的架构，扩展出协作编辑、云端模板库、私有化部署等高级功能。
8. 获取与使用建议
- 下载项目后，直接运行源码或打包好的 EXE 即可开始使用。软件右侧默认会显示使用说明面板，涵盖了所有基础操作。
- 若需定制新的图形或整体样式，主要修改
node_item.py 和 edge_item.py 中的图元绘制逻辑，并可在 main.py 中调整全局主题。
- 当你需要为项目添加文件保存功能时，可以在预留的
model/ 目录下补充 JSON 序列化与反序列化的代码，并将其与主窗口的菜单或快捷键关联。
希望这个项目能为你学习 PySide6 和桌面端 GUI 开发提供一条清晰的实践路径。如果你在开发类似工具或对架构设计有更多想法，欢迎在技术社区交流探讨。
发表于 16 小时前
|
查看: 2|
回复: 0
