简介:一套基于Qt框架的甘特图组件实现,面向需要在桌面应用中展示项目时间线、任务进度或进行项目管理的开发者,特别适合想研究自定义控件源码的中高级Qt用户。该版本来自开源仓库GanttMel-master,以可编译的完整项目形式呈现,压缩包内共27个文件,主要包含5个C++源文件、5个头文件以及2个UI界面文件,同时附有可执行程序、工程配置文件、Qt资源文件和说明文档,整体仅1.69MB,结构精简便于按模块阅读。已有860人学习下载。通过逐行研读源码,可以掌握甘特图核心实现:如何基于QGraphicsView与QGraphicsItem绘制任务条形,如何将时间戳换算为像素坐标并绘制时间轴,如何重写paint()实现自定义外观,以及鼠标拖拽、滚动布局、动画过渡等交互细节。同时,项目展示了MVC数据绑定与性能优化思路,便于开发者直接复用或扩展任务依赖、里程碑等高级功能,是一份轻量而实用的Qt实战学习资料。
1. Qt 甘特图两个版本怎么选:结论放最前面
我在给某跨平台系统做排期模块的时候,把网上流传的经典甘特图 demo 和另一个被社区传了无数次的“另一个版本”都拉下来完整跑了一遍。两个版本界面长得几乎一样,底层却完全不是一回事:经典版用 QTableWidget 拼任务表加自绘时间轴,另一个版本直接拿 QGraphicsView 重建了整个绘制体系。我的结论很直接:任务量在几百条上下、只需要展示和简单编辑,经典表格版足够用;但你需要时间轴缩放、任务拖拽改期、泳道折叠这类交互时,另一个版本从性能和扩展性上都明显占优。这篇文章就把我的比对依据和翻车经历摊开讲,给还在选型的你省点时间。
2. 为什么存在“另一个版本”:从表格拼接换到场景自绘
甘特图看起来就是左侧一个任务列表,右侧一根根彩条按时间铺开,似乎不管怎么实现都差不多。但一旦深入交互,两套方案的差别会被迅速放大。理解这个差别,比急着比较性能数字更重要,因为后面所有选型判断都建立在结构认知上。
2.1 经典版:QTableWidget + 自绘区域的组装思路
最早流传的经典版大多是一主一辅的结构,左侧 QTableWidget 放置任务编号、名称、起止时间等业务列,右侧一个 QWidget 子类负责画时间轴网格、周末底色和任务条。两个区域之间的横向滚动由一个 QScrollBar 联动,或者更省事的写法是让右侧 QWidget 监听左侧表格的滚动条值,再调用自身的 scroll 函数。
这个方案里,所有甘特图的绘制逻辑都被压进 paintEvent。每次滚动、每次数据变化、每次窗口拉伸,QPainter 都要把当前可见范围内的网格和任务条重新画一遍。任务条少时看不出问题,几百条以后,paintEvent 的计算量直线上升,界面就会开始掉帧和闪烁。我最早拿到的那个 demo,200 多条任务时还算顺滑,加到 700 条再拖动窗口,就能明显感觉到绘制滞后。
真正让我头疼的是命中检测。经典版里鼠标事件发生在右侧绘制控件上,我得在 mousePressEvent 里逐个遍历任务矩形,判断点是不是落在某条上,拖拽时还要根据鼠标横向位移换算成时间差。这个逻辑本身不复杂,但和 paintEvent 里的绘制逻辑、坐标换算逻辑混在一起,改一处要连带看三处,很容易出现“拖倒是能拖,改完时间文字却错位”的尴尬。
数据一致性是另一个容易被忽略的问题。表格的 Model 维护一份任务数据,右侧绘制控件内部又维护一份坐标计算好的任务结构。业务上改了状态,若没把两份数据同步刷新,表格里显示“已完成”,甘特图上颜色还停在“进行中”。这种 bug 不好追,因为两边代码都看不出错,纯粹是同步时机的问题。我在项目里就为这个加过一层数据对比日志,才定位到漏刷新。
2.2 另一个版本:QGraphicsView + Scene 的自绘思路
所谓“另一个版本”,本质是放弃“表格加自绘控件”的组合,改用 QGraphicsView 加 QGraphicsScene 重建整个甘特图的底层。任务条、时间轴、今日线、依赖箭头全部是 scene 里的 QGraphicsItem,视图只负责把 scene 渲染到屏幕上并分发事件。
这个思路的第一个直接收益是渲染效率。Scene 内部有空间索引,viewport 滚动时只重绘当前窗口内真正可见的 item,而不是把整张图重画一遍。项目到 2000 条任务以内,拖动滚动条基本没有明显掉帧,和经典版的差距在数据量上来之后非常明显。第二个收益是交互集中,鼠标事件先由 view 换算成 scene 坐标,再由 scene 分发到对应的 item。拖拽改期转换成 item 自己处理鼠标事件,不再需要写单独的矩形命中遍历逻辑。
同时缩放也变简单了。view 的 scale 方法直接改变显示比例,scene 里 item 逻辑尺寸不变,绘制结果自动放大缩小。经典版要在 paintEvent 里重新计算时间刻度、网格间距、任务条宽度,自绘版只需要调用 view 层的 scale 接口就行。
代价与收益同样明显。item 坐标、scene 坐标、viewport 坐标三层体系要先搞懂,SceneRect 如果设置不当,缩放或者滚动时内容会跑到视口外面。item 的绘制函数也得遵守“在 item 坐标里画、不要自己乘缩放系数”的规则。我刚开始接触时,为了确认坐标关系在代码里加了大量临时输出,才把这个体系给理顺。
2.3 迁移成本:从表格版换到自绘版实际要改什么
如果你已经有了一段经典版代码,换到另一个版本并不是替换一个控件那么轻松。数据模型可以不动,但绘制替换和事件替换是两件必须做的事。最快的落地路径是保留原来的业务 Model,新增一个适配层,把任务数据转换成 scene item;先把右侧绘制区全部替换成自绘版,左侧表格留着用于编辑和展示业务字段。这样每改一步都可以随时编译验证。
我在项目里就是这么过渡的:左侧 QTreeView 承担任务树和状态编辑,右侧 QGraphicsView 负责时间可视化。两者通过同一个 Model 的 dataChanged 信号同步更新。好处是业务模型稳定,后续增加依赖箭头、泳道折叠都不需要动左侧结构;坏处是左侧表格和右侧场景之间的行高对齐、滚动同步仍要做一次适配,这部分没有想像中简单,但也比在经典版里维护一套越来越大的 paintEvent 轻松。
还有个很容易忽略的点:另一个版本的源码量和复杂度远超经典版,新人接手需要先看 SceneRect 和坐标映射代码。如果你所在团队没有人熟悉 QGraphicsView,初次评估时要把学习成本算进迁移成本里,否则很容易出现“代码是新的,但没人敢改”的僵局。
3. 四个维度对比:数据量、交互、定制、维护的风险账
我把两个版本放进同一份需求里,各自跑了演示、改功能、压数据,最终总结出四个最关键维度。先用表给出结论,后面再逐条解释判断依据。
| 对比项 | 经典表格版 | 另一个版本(自绘版) |
|---|---|---|
| 数据规模 | 500 条左右开始掉帧,1000 条以上体验不佳 | 2000 条以内流畅,更高需配合合并绘制和 LOD |
| 拖拽与缩放 | 拖拽要手写命中,缩放要重算刻度 | item 事件统一,缩放走 view 层 transform |
| 定制扩展 | 加业务列容易,加图形交互困难 | 加图形能力强,加文本列需要自己处理 |
| 维护风险 | 代码直白,但 paintEvent 逻辑累赘 | 概念多、源码量大,依赖团队熟悉度 |
3.1 数据规模:500 条是坎,2000 条是分水岭
经典版的性能瓶颈来自整区域重绘。任务条数量少的时候,paintEvent 画几百个矩形还不成问题,数量涨到上千,一次滚动就要重复计算和绘制,帧率就稳不下来。如果任务条本身还有渐变、圆角、阴影这类效果,性能下降会更明显,因为这些效果在一次次重绘中的计算量远高于纯色矩形。
自绘版并不是完全没上限。当 item 数量上万后,BSP 空间索引本身的维护和重建也会变成负担。常规优化是合并同泳道的小任务为一个 item 绘制,或者在任务数大且需要整体移动时把索引切换为 QGraphicsScene::NoIndex,以及按缩放级别对时间刻度做 LOD。把这些手段用上之后,任务数即使到五六千条,实际体验也能压到可接受范围。
我一般会这么判断:如果你的业务固定只有一两百条任务,且不会增长太多,经典版完全够用;如果是长期运行的排期系统,任务量动辄上千,直接考虑自绘版,否则后期性能优化会把人力吞掉一大半。做基准测试时不要把任务条排成整齐一列,要模拟真实的时间分布和层级关系,因为随机分布下的 hit 检测和重绘压力要比整齐排列大得多,测出来的数字才可信。
3.2 交互能力:拖拽、缩放、折叠的实现差异
任务拖拽改期这个功能最能区分两套方案。经典版要在鼠标事件里先遍历所有任务条,判断点落在哪一条,再根据鼠标水平位移换算成天数,修改数据后主动触发重绘。逻辑不复杂,但代码分散在三个事件函数里,后续要加“拖拽时显示日期提示”又要在鼠标移动事件里加一段换算。
自绘版只需要重写任务条 item 的 mousePressEvent、mouseMoveEvent 和 mouseReleaseEvent,维护的是 item 自己的业务数据。至于鼠标当前在哪、x 坐标差对应几天,都可以通过 scene 坐标换算直接得到,代码集中在一处,后期维护成本小很多。
折叠展开也是经典版的弱项。表格可以隐藏行,但右侧绘制区不知道哪些行被隐藏了,必须让两个区域的行高和位置保持一致,折叠一次要把两份数据重新对齐。自绘版的折叠则简单得多:把某个泳道分组里的 item 设为不可见,或者整体移出可视区域,不需要和表格行高联动。
时间轴缩放就更是自绘版的强项。view 的 scale 方法直接改变显示比例,scene 里 item 逻辑尺寸不变,绘制结果自动放大缩小。经典版要在 paintEvent 里重新计算时间刻度、网格间距、任务条宽度,逻辑很容易出边界 bug。如果需求里明确要“按周展开再按天展开”,自绘版才是更稳的选择。
3.3 定制成本:加业务列和加图形交互是两回事
我最初以为自绘版做什么都快,直到想往界面里加一列“负责人”文本时才发现,场景里没有现成的表格列概念。要在每条任务旁边显示一个名字,得用 QGraphicsTextItem 或者自己在 paint 里画文本,还要处理换行、对齐和滚动。而这在经典的 QTableWidget 方案里就是 addColumn 加一个委托的事。
反过来,如果要在甘特图上加依赖箭头,经典版需要在 paintEvent 里根据两个任务条的位置画一条线,还得在鼠标事件里为这条线做命中判断;而自绘版直接往 scene 里 addItem 一个连接线就行,改动范围和后续维护都是局部的。
所以选型之前把“以后要加的需求”按表格类和图形类分开列一下。偏表格类的多,经典版更划算;偏图形类的多,自绘版优势更大。很多时候项目是因为需求列表里图形类功能越加越多,才不得不从经典版迁到另一个版本。做这个分类时,最好把“需求会不会变”也写进去,因为图形类需求往往是在做出来之后才被人想出来的。
3.4 维护风险:代码量和团队认知度同样重要
经典版的代码量小,逻辑直白,团队里任何一个有 Qt 基础的人都能改。缺点在于所有逻辑都压在 paintEvent 和 mouse 事件里,功能越加越乱,最终的维护成本可能从线性变成非线性上涨。有没有人敢重构这段代码,往往是决定长期维护质量的关键。
自绘版的源码量通常是经典版的数倍,概念也多。但如果团队里有一个人能把 QGraphicsView 讲清楚,后续改动的粒度反而是清晰的:新增一种 item、改一种 item、删一种 item,不需要穿越整个文件去理解全局。可怕的是没人懂,所有坐标问题都变成玄学,谁也不敢动。
还有一个要评估的点是来路。网上流传的经典版经过多年检验,兼容性坑大多被人踩平了;而另一个版本往往源自个人开发者,对 Qt 版本、编译器的验证范围有限。我拿到的那份工程在某个 Qt 版本上没问题,换到另一个环境编出的界面在缩放时会出现细微错位,最后还是要自己上手修。选型时要把这个“来路风险”也记一笔。
4. 避坑记录:坐标、缩放、滚动同步的几个实战问题
自绘版和经典版各有各的坑,但都是可排查的。下面按现象、原因、解决写五条我真实踩过、也帮别人处理过的问题,很多问题不是因为代码难,而是因为变量太多找不到方向。
4.1 坐标换算错乱:任务条整体飘到视口外
现象:自绘版里任务条显示位置不对,滚动或缩放后会突然跑出可视区域,有时候又像是被截断;鼠标悬停的 tooltip 位置和任务条本身也不一致。
原因:最常见的直接把 view 的 viewport 坐标和 scene 坐标混用了。view 上的设备坐标原点在视口左上角,scene 坐标原点在 scene 的坐标系里,两者之间由 view 的 transform 和滚动偏移共同决定。一旦窗口拖动、滚动条变动,混用结果就是错误的。还有人把 item 的 pos() 和 scenePos() 当成一回事,但 item 有父节点时,pos() 是相对父节点的。
解决:在事件和业务代码中统一用 mapToScene 把鼠标位置转成 scene 坐标,再与 item 的 scenePos 和 boundingRect 判断。千万别在 item 内部用 view 的设备坐标做位置计算。代码 review 时,凡是看到 event->pos() 不经过 mapToScene 就参与业务判断的,直接按异常处理。另一个隐蔽点是,如果你给 item 设置了父 item,setPos 传入的是相对父节点的坐标,判断是否命中时则要用 scene 坐标,这两个值不能混着来。
4.2 缩放后显示乱:条宽变形加上时间刻度过密
现象:放大后任务条显示异常,拖拽手柄和条的位置对不上,有些 item 的文字被拉伸;同时缩到月级别时,时间刻度又密到重叠,肉眼分不清数字,整个刻度带变得一团糟。
原因:第一个是绘制逻辑里手动乘了缩放系数,paint() 里用 view 的 scale 值再乘一次坐标,等于系统中出现了两次缩放;第二个是时间刻度没有做 LOD,无论缩放级别是多少,都按初始粒度画刻度,缩得越远景越乱。这两个问题往往同时出现,排查时先确定是绘制变形还是刻度计算问题,再分头动手。
解决:在 item 的 paint() 里只用 item 坐标绘制,缩放全部交给 view 完成。时间刻度改成根据当前缩放比例动态选择粒度,比如放大到天级别画小时线,缩到周级别只画日期,月级别只画月份。同时,对 item 的 boundingRect 之外做裁剪,避免不可见刻度参与绘制开销。改完之后你再缩放,视口内只重绘当前粒度需要的刻度,性能和显示都会恢复正常。
4.3 表格版滚动不同步和行高错位
现象:经典版中左侧表格和右侧绘图区在横向滚动时有时错位,拖动滚动条时出现回弹或跳动;展开或折叠某行后,任务条与表格中对应的行也对不上。
原因:两个区域分别有自己的滚动机制,如果互相向对方 setValue 形成循环触发,就会出现回弹。行高错位则是表格行高和绘制区行高来自两套计算,字体和边距稍不一致,逐行积累出明显偏差。还有一个常见诱因是表格启用了自动行高,字体变化后行高被悄悄改掉,但绘制区仍按旧行高画。
解决:两个区域共用一个 QScrollBar,或者是一个主滚动条驱动另一个,被驱动方向的滚动事件不再反向触发。行高从同一个配置常量读取,关闭表格自动调整行高,并且在设置字体后手动重算固定行高。我后来把这两个逻辑都改成从共享配置读取,类似的问题就再没出现过。如果你还要做筛选功能,记得筛选导致行数变化时同步重算绘制区的可见行范围,否则筛选后第一行对应的任务条也会错位。
4.4 自绘版批量操作卡顿:BSP 索引是双刃剑
现象:单个任务条移动流畅,一旦整个泳道里的几百个任务条一起移动,或者连续刷新多条数据时,界面会有明显卡顿,有时任务条还会短暂闪烁。
原因:QGraphicsView 默认开启 BSP 空间索引,item 位置大量变动时,索引要反复重建,重建消耗反而比省下的命中查询还大。这个场景更合适 NoIndex 模式。很多人以为默认开启的索引一定最好,其实索引的适用场景是 item 多但位置相对稳定,批量移动时不断更新索引反而成为瓶颈。
解决:把大批量移动的 item 放在 scene 的 NoIndex 模式下,或者用一个容器 item 包住整组,只移动外层 item,减少索引重建次数。判断依据是:如果 item 数量没有特别巨大但移动频繁,就尝试 NoIndex 对比测试;移动不频繁但 item 极多,则保留 BSP。我对比过 500 个 item 同时位移的场景,NoIndex 比默认索引快接近一倍。这个参数没有绝对答案,要以实际 profile 为准而非纯理论下结论。
5. 最终选型结论与自查清单
如果你看重落地速度,任务量几百条以内,团队里没有人深入研究过 QGraphicsView,那经典表格版是更务实的选择。不要因为“听说自绘版性能好”就强行切换,性能优势要在工程量放大之后才体现出来;反过来,如果你的需求里已经明确有时间轴缩放、依赖箭头、泳道折叠,或者任务量过千,那经典版改起来才是真的烧时间。
还有一个更具体的判断信号:把功能需求按“表格类”和“图形类”分开,图形类需求超过两三个,基本就该看向另一个版本。选型不是选更高级的,而是选落地更容易的。我最后选了自绘版,不是因为它新,而是因为我们要做依赖箭头和按周缩放,经典版那套结构改起来成本太高。
如果你决定走自绘版,我建议按这几步入手:先跑通 demo,不接业务逻辑;把 SceneRect 设置成固定时间范围;用 mapToScene 统一事件坐标;然后把所有 item 的数据源集中在一个 model 里。我这样连续跑了两周,只改出三个问题,其中两个还是字体相关。
再回头想,如果当时没做这轮对比,直接拿第一个版本上线,后面大概率要在“滚动不同步”和“paintEvent 越写越长”这两个坑里反复挣扎。从那以后,我每次接这类带时间轴的组件,都会把交互清单先列出来,对照着数据量和团队维护能力去选型,而不是看哪个 demo 第一眼更顺眼。希望帮到你。
244



被折叠的 条评论
为什么被折叠?



