简介一套基于 Qt 实现甘特图的 C 源码面向需要为项目管理、任务排期类软件补充时间轴视图的开发者也适合想练习自定义图形控件的中级 Qt 学习者。代码围绕 QGraphicsView 与 QGraphicsScene 组织图形项用 QPainter 按任务起止时间计算矩形长度完成绘制并以结构体保存任务名称、时间范围、优先级等字段拖动、点击等交互通过重写鼠标事件响应数据变动则借助信号与槽驱动视图刷新整体按数据、绘制、交互分层拆分便于二次修改与移植。资源包共 12 个文件压缩后约 14KB其中 5 个 .h 头文件承担结构与类声明4 个 .cpp 源文件实现主逻辑及新增、修改对话框另有 .pro 工程文件、.user 本地配置和一份 txt 说明用 Qt Creator 打开即可查看工程组织。目前已有 3112 人学习适合用来理解时间序列数据如何映射为可视化图形。1. 先把场景说透Qt 甘特图源码解决的是任务行与时间条的坐标映射项目排期表一旦从表格搬到桌面端最容易被低估的就是任务条和任务行之间的坐标换算这也是我拆这份 Qt 甘特图源码时最先看的地方。它做的不是“画几条彩色横条”而是把任务开始时间、结束时间、依赖关系、拖拽改期和缩放浏览落到一个可交互控件里。适合两类人一类是手里已经有任务表需要快速做一个排期视图的开发者另一类是想在 Qt Widgets 里练手时间轴、命中测试和自绘控件的人。源码能不能直接跑起来关键不在界面多漂亮而在任务模型、时间轴换算和刷新链路有没有拆干净。2. 工程骨架与模块边界Qt 甘特图源码里谁管数据、谁管画布、谁管时间轴2.1 先按职责认目录不要急着改界面拿到一份 Qt 甘特图源码我一般先不看主窗口长什么样而是按职责找三类文件任务数据放哪、时间换算放哪、绘制和鼠标事件放哪。不同源码的命名差异很大常见文件名可能是ganttwidget.cpp、timeline.cpp、taskmodel.cpp也可能全部塞进一个控件类里。名字不重要职责边界才重要。下面这个目录结构是这类工程常见的归类方式用来看清模块关系不是要求源码必须一字不差project/ ├─ widgets/ // 甘特图控件、表头、左侧任务列 ├─ model/ // TaskItem、任务集合、依赖关系 ├─ axis/ // 时间轴换算、缩放、刻度 ├─ delegates/ // 如果走 QGraphicsView这里放 item 绘制 └─ app/ // 启动窗口、示例数据、菜单和工具栏这段结构只表达一件事数据模型不要直接依赖QPainter时间轴不要依赖具体控件尺寸绘制层再去拿模型和轴。很多源码一开始能跑二次开发时一改就乱根子是把TaskItem的字段、像素坐标和鼠标临时状态混在同一个类里。判断方法很直接如果paintEvent里出现大量startDate.daysTo(...)和硬编码x 120时间换算就没有独立出来如果任务条位置靠row * 30硬算行高和滚动偏移后面一定翻车。模块常见职责二次开发入口任务模型保存任务 id、标题、起止时间、依赖、行号、颜色换字段、接数据库、加负责人时间轴时间到 x 坐标、x 坐标回时间、缩放和刻度改日/周/月视图、加工作日甘特图控件绘制表头、网格、任务条、依赖线处理鼠标改交互、加右键菜单、加编辑弹窗主窗口装载示例数据、放滚动区域、连接信号替换真实任务表、接刷新逻辑这张表里最值得先动的是任务模型和时间轴不是颜色。任务模型如果没有稳定id依赖线只能用标题匹配改个任务名就断时间轴如果只保存“每天多少像素”缩放和滚动一起上来就会错位。常见做法是让任务模型只存业务时间让时间轴负责把时间映射到控件坐标绘制层每次通过barRect(task)拿矩形。这样后面接真实任务流时替换数据源不会牵动绘制代码。2.2 三条主链路数据装载、坐标换算、绘制刷新这份 Qt 甘特图源码可以按三条链路拆。第一条是数据装载示例数据或外部任务表进入QVectorTaskItem同时建立id - index的索引依赖线靠 id 找前驱。第二条是坐标换算时间轴拿到视图范围、任务列宽度、表头高度、滚动偏移算出任务条的QRectF。第三条是绘制刷新paintEvent按表头、网格、任务列、任务条、依赖线的顺序画鼠标事件只改模型字段然后update()触发重绘。三条链路中任何一条把“像素”和“时间”混着存后面都会出现玄学偏移。我习惯先让空数据版本跑起来再塞两三条固定任务最后才接真实数据。空数据版本能验证主窗口、滚动区域和表头高度两条任务能验证时间轴和行号依赖线放最后因为它最容易掩盖坐标错误。源码如果自带示例数据不要一上来删光先保留示例跑通再把示例数据替换成自己的任务集合。这样出问题时能判断是源码本身没跑通还是自己的数据格式接错了。编译入口先看根目录有.pro走 qmake有CMakeLists.txt走 CMake两者都没有就先确认源码是不是只给了核心类文件。2.3 编译和首启步骤目标名以工程文件为准编译命令不要照抄可执行文件名先看工程文件里的TARGET。下面用YourGanttApp占位实际替换成源码里的目标名。qmake 路线适合老工程CMake 路线适合已经带CMakeLists.txt的源码两条路线不要同时在一套构建目录里混用否则中间文件会互相污染。# 1. 先看根目录入口.pro 和 CMakeLists.txt 通常只留一个 ls # 2. qmake 路线YourProject.pro 换成实际工程文件名 qmake YourProject.pro make -j4 ./YourGanttApp # 3. CMake 路线没有 .pro 时优先试这个 cmake -S . -B build cmake --build build -j4 ./build/YourGanttApp这段命令里-S .表示源码根目录-B build表示把中间文件放到build避免污染源码-j4是并行编译数机器核少就改成-j2。Windows 下 qmake 路线可能是mingw32-make或nmakeCMake 路线统一用cmake --build build更稳。首启后先看三件事窗口有没有出现、表头有没有日期刻度、示例任务条有没有落在正确行。如果窗口出现但一片空白先别怀疑绘制算法优先查控件尺寸、滚动区域和update()有没有触发这类问题在避坑章会细拆。3. 核心数据模型与时间轴换算任务条位置为什么总差半天3.1 TaskItem 字段设计时间用 QDateTimeid 要稳定任务条错位最常见的原因不是绘制而是模型字段设计太省。只用QDate存开始和结束任务条默认都落在当天零点遇到半天粒度、跨时区导出或者“结束日期含当天”就会差半天。我的建议是模型内部统一用QDateTime展示层再决定按天还是按小时对齐。id必须稳定依赖关系用它做 key不要用标题row可以缓存但排序后要重算。下面这段是这类工程里常见的模型骨架struct TaskItem { int id -1; // 稳定主键依赖线用它找前驱 QString title; // 任务名只用于显示 QDateTime start; // 业务开始时间建议统一时区 QDateTime end; // 业务结束时间结束是否含当天由业务决定 QVectorint dependsOn; // 前驱任务 id 列表 int row -1; // 缓存行号排序后必须重算 QColor color QColor(#4C8BF5); };这段代码的关键在start/end用QDateTime以及id和row分开。id是业务主键row是界面排序后的位置两者不能混用依赖线如果拿row当 id任务一排序就全断。dependsOn存前驱 id绘制时通过id - index的QHash找任务找不到就跳过不要崩。color可以留在模型里做简单分类但更规范的做法是放展示配置避免模型依赖 UI 类型。参数上唯一要提前定的是结束时间语义如果业务表里“结束日期”表示含当天模型里可以存当天 23:59:59或者在时间轴换算时加一天二者只能选一个不能绘制层加一次、导出层又加一次。3.2 时间到像素的换算函数所有 x 坐标都从这里出时间轴的核心只有两个方向xForTime(t)把时间变成控件 x 坐标timeForX(x)把鼠标 x 坐标变回时间。很多源码在paintEvent里直接写(start.daysTo(end)) * dayWidth画是能画但滚动、缩放、命中测试各写一套后面必出偏差。我一般把范围起点、范围终点、绘图区宽度、左侧任务列宽收进一个TimeAxis绘制和鼠标命中共用同一套换算class TimeAxis { public: void setRange(const QDateTime start, const QDateTime end, int viewWidth) { m_rangeStart start; m_rangeEnd end; m_viewWidth qMax(1, viewWidth); // 绘图区宽度不含左侧任务列 } qreal xForTime(const QDateTime t) const { const qint64 totalMs m_rangeStart.msecsTo(m_rangeEnd); if (totalMs 0) return m_leftPadding; const qreal ratio qreal(m_rangeStart.msecsTo(t)) / qreal(totalMs); return m_leftPadding ratio * plotWidth(); } QDateTime timeForX(qreal x) const { const qreal left m_leftPadding; const qreal right m_leftPadding plotWidth(); const qreal clamped qBound(left, x, right); const qreal ratio (clamped - left) / plotWidth(); const qint64 ms qint64(m_rangeStart.msecsTo(m_rangeEnd) * ratio); return m_rangeStart.addMSecs(ms); } qreal msForPixels(qreal dx) const { const qint64 totalMs m_rangeStart.msecsTo(m_rangeEnd); return plotWidth() 0 ? qreal(totalMs) * dx / plotWidth() : 0; } private: qreal plotWidth() const { return qMaxqreal(1.0, m_viewWidth - m_leftPadding - m_rightPadding); } QDateTime m_rangeStart; QDateTime m_rangeEnd; int m_viewWidth 0; int m_leftPadding 220; // 左侧任务列宽度 int m_rightPadding 20; };这段逻辑里m_rangeStart/m_rangeEnd是时间轴可见范围m_viewWidth是绘图区总宽m_leftPadding是左侧任务列占掉的宽度plotWidth()才是真正画任务条的宽度。xForTime用毫秒比例算不用“天数乘固定宽度”这样小时粒度和跨月都能用。timeForX先qBound再反算避免鼠标拖出边界后得到离谱时间。msForPixels专门给拖拽用鼠标移动dx像素对应多少毫秒的时间差直接拿它加减原始时间比每帧重新timeForX再取整更稳。参数上要改的是m_leftPadding和m_rightPadding它们必须和绘制表头、任务列的实际宽度一致否则任务条会整体偏移。3.3 行号、滚动偏移和点击命中别把控件坐标直接当绘图坐标任务条的 y 坐标来自行号、行高、表头高度和纵向滚动偏移点击命中也要走同一套。常见错误是mousePressEvent里用event-pos().y() / rowHeight直接取行号忘了减表头高度也忘了加滚动偏移结果一滚动就点错行。下面这段命中函数把表头、滚动偏移和行号边界都收在一起int GanttWidget::rowAt(const QPointF pos) const { if (pos.y() m_headerHeight) return -1; // 表头不参与任务命中 const qreal y pos.y() - m_headerHeight m_scrollY; // 加回纵向滚动偏移 const int row int(y / m_rowHeight); return (row 0 row m_tasks.size()) ? row : -1; } QRectF GanttWidget::barRect(const TaskItem t) const { const qreal x1 m_axis.xForTime(t.start) - m_scrollX; const qreal x2 m_axis.xForTime(t.end) - m_scrollX; const qreal y m_headerHeight t.row * m_rowHeight - m_scrollY 6; return QRectF(QPointF(x1, y), QPointF(qMax(x1 2.0, x2), y m_rowHeight - 12)); }rowAt里pos.y() m_headerHeight挡住表头 m_scrollY把控件坐标还原到内容坐标barRect里- m_scrollX和- m_scrollY把内容坐标转成当前可见坐标。m_rowHeight要固定行高如果随字体变化就必须用每行几何缓存不能再用乘法。qMax(x1 2.0, x2)是给零工期任务留最小宽度不然画不出来也点不中。参数上m_headerHeight、m_rowHeight、m_scrollX/Y必须和滚动区域、表头绘制共用同一组值我一般把它们放在控件类里做成员避免绘制和命中各拿一份。这里最容易留下的后悔药是“先写死 30 像素行高后面再改”等字体一换、高 DPI 一开行号和任务条就对不上。4. 绘制与交互落地QPainter 画任务条鼠标事件改工期4.1 paintEvent 的绘制顺序先网格后任务先任务后依赖自绘甘特图最怕绘制顺序乱。我的习惯是固定五层背景、表头刻度、左侧任务列、网格、任务条、依赖线。依赖线放任务条后面避免线头盖住任务名表头单独裁剪避免任务条画到表头区域。下面这段paintEvent是这类控件的常见骨架具体函数名按源码调整void GanttWidget::paintEvent(QPaintEvent*) { QPainter p(this); p.setRenderHint(QPainter::Antialiasing, true); p.fillRect(rect(), Qt::white); p.save(); p.setClipRect(QRectF(0, 0, width(), m_headerHeight)); drawHeader(p); // 日期刻度、周/月分组 p.restore(); p.save(); p.setClipRect(QRectF(0, m_headerHeight, m_taskColumnWidth, height())); drawTaskColumn(p); // 左侧任务名不随横向滚动 p.restore(); drawGrid(p); // 只画绘图区网格 for (const TaskItem task : m_tasks) { const QRectF bar barRect(task); if (!bar.intersects(rect())) continue; // 简单可视裁剪 p.setPen(Qt::NoPen); p.setBrush(task.color); p.drawRoundedRect(bar, 4, 4); p.setPen(Qt::black); p.drawText(bar.adjusted(6, 0, -6, 0), Qt::AlignVCenter | Qt::AlignLeft, task.title); } drawDependencies(p); // 依赖线最后画 }这段顺序里drawHeader用setClipRect裁到表头高度防止刻度文字溢出drawTaskColumn裁到左侧列宽保证横向滚动时任务名不动任务条循环里用bar.intersects(rect())做简单裁剪任务多时能省一部分绘制。barRect(task)已经处理了滚动偏移所以这里不要再减一次。参数上m_headerHeight、m_taskColumnWidth、m_rowHeight要和TimeAxis的m_leftPadding对齐。注意QPainter::Antialiasing打开后圆角更顺但大量任务条时会有性能开销任务上千再考虑按可视区域裁或者换QGraphicsView不要一开始就过度设计。4.2 拖拽改开始时间和拖拽改工期用像素差换时间差任务条拖拽通常有两种模式拖条身改开始时间拖右边缘改结束时间。关键是按下时记录原始时间和鼠标起点移动中用msForPixels(dx)算时间差不要每帧用timeForX反算再取整否则会越拖越偏。下面这段是常见实现void GanttWidget::mousePressEvent(QMouseEvent* e) { if (e-button() ! Qt::LeftButton) return; const QPointF pos e-position(); // Qt5 可换成 e-pos() const int row rowAt(pos); if (row 0) return; const QRectF bar barRect(m_tasks[row]); if (!bar.contains(pos)) return; m_dragTaskIndex row; m_dragMode (pos.x() bar.right() - 8) ? ResizeEnd : MoveTask; m_dragStartPos pos; m_dragOriginStart m_tasks[row].start; m_dragOriginEnd m_tasks[row].end; } void GanttWidget::mouseMoveEvent(QMouseEvent* e) { if (m_dragTaskIndex 0) return; const QPointF pos e-position(); const qreal dx pos.x() - m_dragStartPos.x(); const qint64 ms qint64(m_axis.msForPixels(dx)); if (m_dragMode MoveTask) { m_tasks[m_dragTaskIndex].start m_dragOriginStart.addMSecs(ms); m_tasks[m_dragTaskIndex].end m_dragOriginEnd.addMSecs(ms); } else { m_tasks[m_dragTaskIndex].end m_dragOriginEnd.addMSecs(ms); if (m_tasks[m_dragTaskIndex].end m_tasks[m_dragTaskIndex].start) m_tasks[m_dragTaskIndex].end m_tasks[m_dragTaskIndex].start.addDays(1); } update(); }m_dragMode区分移动和改工期m_dragOriginStart/End保存按下瞬间的原始值msForPixels(dx)把像素差换成毫秒差。右边缘命中用bar.right() - 88 像素是手柄热区可按源码调整。改工期时做下限保护防止结束时间早于开始时间。参数上拖拽后要不要按天对齐由业务决定排期表通常按天QDateTime可以先算毫秒再addDays或把时间截到 00:00如果是小时级排班就不要截断。mouseReleaseEvent里记得清空m_dragTaskIndex并发出任务变更信号让主窗口决定是否写回数据库。这里翻车的典型场景是拖拽时只改界面缓存、不更新模型松手后一刷新又弹回去。4.3 依赖线和缩放坐标都从 barRect 出锚点要锁在鼠标下依赖线不要自己再算一遍任务条坐标全部走barRect这样滚动和缩放自动一致。线从后置任务的前驱右边缘中点连到当前任务左边缘中点用二次贝塞尔拐一下避免直线穿过任务条void GanttWidget::drawDependencies(QPainter p) { p.setPen(QPen(QColor(#8A94A6), 1.5)); p.setBrush(Qt::NoBrush); for (const TaskItem task : m_tasks) { for (int predId : task.dependsOn) { const TaskItem* pred findTaskById(predId); if (!pred) continue; // 依赖缺失时跳过不崩 const QRectF a barRect(*pred); const QRectF b barRect(task); const QPointF s(a.right(), a.center().y()); const QPointF e(b.left(), b.center().y()); const qreal mid (s.x() e.x()) / 2.0; QPainterPath path(s); path.cubicTo(QPointF(mid, s.y()), QPointF(mid, e.y()), e); p.drawPath(path); } } }这段逻辑里findTaskById用 id 找前驱找不到就跳过避免数据脏了直接崩。控制点mid取两端 x 中点线会先横后竖视觉上比直线清楚。缩放用Ctrl 滚轮时要以鼠标位置为锚点否则一缩放视图就跳走void GanttWidget::wheelEvent(QWheelEvent* e) { if (!(e-modifiers() Qt::ControlModifier)) { QWidget::wheelEvent(e); return; } const QPointF pos e-position(); const QDateTime anchorTime m_axis.timeForX(pos.x() m_scrollX); const qreal factor e-angleDelta().y() 0 ? 1.1 : 0.9; m_axis.setZoom(m_axis.zoom() * factor); m_scrollX qMax(0.0, m_axis.xForTime(anchorTime) - pos.x()); update(); }anchorTime是缩放前鼠标下的时间缩放后重新算它的 x再把滚动偏移调到鼠标位置视觉上就是“时间没跑”。angleDelta().y()正负决定放大缩小factor按源码手感调常见 1.1/0.9。参数上m_axis.setZoom要真的影响绘图区宽度或每日像素宽不能只存一个变量不参与换算如果源码用固定dayWidth就把缩放实现换成改dayWidth并重算范围。依赖线和缩放都共用barRect和TimeAxis这是减少错位的根本。5. 运行与避坑排查Qt 甘特图源码从编译到首屏渲染5.1 首次运行检查清单先让空数据版本出画面首启不要直接塞真实任务表。先跑源码自带示例再跑空数据版本最后替换两三条固定任务这是最省时间的顺序。检查清单可以按这个顺序走工程能不能编译、主窗口能不能出现、甘特图控件有没有拿到非零尺寸、表头有没有画出来、任务条有没有落在第一行、滚动后任务条和任务列是否同步。控件尺寸是重灾区很多自绘控件在布局里没设最小尺寸首屏width()或height()是 0paintEvent画了也看不见。可以在resizeEvent里打印一次尺寸确认布局真的把空间分给了甘特图控件。void GanttWidget::resizeEvent(QResizeEvent* e) { QWidget::resizeEvent(e); const int plotWidth width() - m_taskColumnWidth; m_axis.setRange(m_rangeStart, m_rangeEnd, plotWidth); qDebug() gantt size size() plotWidth plotWidth; update(); }这段resizeEvent做两件事把控件宽度减去左侧任务列宽后交给时间轴然后触发重绘。m_taskColumnWidth必须和绘制任务列、TimeAxis左边距一致plotWidth小于 1 时时间轴内部会兜底但界面仍然会挤成一条线。qDebug只在排查时留正式版可以删。参数上如果源码用QScrollArea包住甘特图控件控件的width()可能等于内容宽度而不是视口宽度时间轴要拿视口宽度不能拿控件宽度。这个差别不搞清横向滚动一定错位。5.2 常见问题排查记录五条血泪经验现象一窗口能出来甘特图区域一片空白。原因通常是控件尺寸为 0或者示例数据在控件构造前就被清空paintEvent里没有任务可画。解决是先注释掉清空数据的代码保留源码示例确认表头和网格能出来再在resizeEvent打印尺寸给控件设setMinimumSize(600, 400)检查布局有没有把控件挤没。如果表头也没有查paintEvent有没有被重写后忘了调QWidget::paintEvent或者父控件把子控件遮住了。现象二任务条整体偏左或偏右滚动后偏移更大。原因是TimeAxis的左边距和绘制任务列的宽度不一致或者barRect减了滚动偏移、paintEvent又减了一次。解决是把任务列宽、表头高度、滚动偏移收成一份成员变量绘制和命中共用在barRect里只减一次m_scrollX其他地方不要再减。检查时让时间轴范围固定为 7 天画一条从范围起点到终点的任务看它是否正好铺满绘图区偏一点都能暴露左边距问题。现象三拖拽改期后任务条跳动松手时间不对。原因是拖拽过程中每帧用timeForX反算再取整误差累积或者按下时没保存原始时间直接在当前值上累加。解决是按 4.2 的做法保存m_dragOriginStart/End用msForPixels(dx)算总差松手再按业务粒度对齐。还要检查mouseMoveEvent里有没有重复触发update()导致重入正常只改模型再请求重绘即可。如果用了QGraphicsView拖拽改的是 item 的pos()还是数据时间必须二选一不能两边都改。现象四依赖线错位任务一排序就全断。原因是依赖关系用行号或标题匹配排序后行号变了、标题改了。解决是模型里保留稳定iddependsOn存 id绘制时用QHashint, int找索引找不到前驱就跳过并打日志不要让空指针崩。依赖线坐标统一从barRect取不要单独算row * rowHeight。如果线画在任务条下面被盖住调整绘制顺序把依赖线放到任务条之后。现象五高 DPI 下字和线发虚任务条边缘模糊。原因是绘制坐标用了整数截断或者没有开抗锯齿、没有处理设备像素比。解决是QPainter打开Antialiasing坐标尽量用qreal不要提前toInt()Qt 的高 DPI 属性按工程现有配置处理不要和源码里的缩放逻辑打架。如果源码自己做了devicePixelRatio缩放绘制和命中测试都要用同一套缩放系数不能只缩绘制不缩鼠标坐标。这个坑最隐蔽因为逻辑坐标看起来是对的只是视觉发虚排查时先打日志看width()和实际像素宽是否一致。6. 二次开发改造把甘特图控件接进真实任务流改造这份 Qt 甘特图源码我建议按“先数据、再交互、后样式”的顺序来不要一上来换皮肤。数据层先把TaskItem换成自己的任务结构保留id/start/end/dependsOn四个字段语义再加负责人、状态、进度交互层先只做拖拽改期和任务点击信号右键菜单、编辑弹窗后面加样式层最后改颜色和圆角。下面这张表可以作为改造检查点改造点落点验证方法接真实任务表示例数据装载处换成数据库/接口查询空表不崩三条任务行号正确加进度百分比TaskItem加progress任务条内再画一层进度 0 和 100 都不越界拖拽写回mouseReleaseEvent发信号给主窗口松手后刷新数据仍保持新时间依赖校验拖拽前检查前驱结束时间依赖不满足时拒绝或标红大任务量只绘制可视区域或换QGraphicsView滚动帧率可接受命中不偏移一个具体技巧是把“时间对齐”做成策略不要散落在鼠标事件里。比如按天排期的系统拖拽结束后统一把开始时间截到当天 00:00结束时间按“含当天”加一天按小时排班的系统保留分钟。下面这个函数可以放在控件或业务层拖拽松手后调用QDateTime GanttWidget::alignToDay(const QDateTime t) const { QDateTime d t; d.setTime(QTime(0, 0)); // 按天排期统一截到当天零点 return d; }alignToDay只做一件事把时间截到天。参数t是拖拽后的原始时间返回对齐后的时间如果业务是“结束日期含当天”在写回前给结束时间加一天但只能加一次。验证时用两条任务一条跨月、一条零工期拖到边界看会不会跑到范围外再刷新一次数据确认界面和模型一致。我踩过一次坑拖拽只改了界面缓存数据库没写回用户一刷新全弹回去后来每次接甘特图源码都先跑空数据、再加真实任务、最后才动交互希望帮到你。本文还有配套的精品资源点击获取