简介:这份源码资源面向具备一定 C++ 与 Qt 基础的开发者,聚焦于在 Qt 环境中实现甘特图这一项目管理可视化组件,可用于任务排期、进度跟踪等场景的二次开发与学习。压缩包共 12 个文件,以 5 个 .h 头文件与 4 个 .cpp 源文件为核心,另含 .pro 工程文件、说明文本及用户配置,整体约 14KB,结构紧凑便于快速通读。源码围绕 QGraphicsView、QGraphicsScene 与 QPainter 构建绘制逻辑,通过自定义图形项表示任务条与时间范围,并借助 QDateTime 处理起止时间与相对时长;数据层以结构体与模型类管理任务名称、优先级等信息,配合信号槽机制在数据变更时刷新视图。事件处理部分覆盖鼠标点击与拖拽,实现任务选择与调整,同时兼顾缩放、滚动与模块化组织。目前已有 3107 人学习,适合希望掌握 Qt 自定义可视化控件与时间序列数据渲染的开发者参考借鉴。
1. 用 Qt 手搓甘特图:从时间轴到拖拽条,这套源码把项目排期画明白了
如果你做过项目管理工具、生产排程系统或者实验室任务看板,大概率绕不开甘特图这个控件。现成的商业库要么贵,要么定制起来处处受限,于是很多团队选择用 Qt 自己画。这份源码就是一个完整的 Qt 甘特图实现,覆盖了时间轴刻度、任务条绘制、拖拽调整工期、依赖连线这些核心能力。它适合两类人:一类是刚接触 Qt 图形视图框架、想找一个真实控件练手的开发者;另一类是在项目里被排期图折磨过、需要一套能直接改的底层的熟手。下面我按“能干什么、怎么跑、怎么改”的顺序,把这份源码拆开讲一遍。
2. 架构与目录:QGraphicsView 体系下的甘特图骨架
2.1 为什么选 QGraphicsView 而不是 QWidget 自绘
甘特图本质上是一张可缩放、可滚动、元素可交互的大画布。用 QWidget 的 paintEvent 硬画也能实现,但一旦任务条数量上去、需要单独选中某一条、需要做碰撞检测,代码就会迅速失控。这份源码选择了 Qt 的 Graphics View Framework,也就是 QGraphicsView + QGraphicsScene + QGraphicsItem 这套组合。
它的好处很直接:每个任务条是一个独立的 QGraphicsItem,选中、悬停、拖拽这些交互由框架帮你分发事件,你只需要在 item 内部处理 mousePressEvent 和 mouseMoveEvent。时间轴刻度、网格线、依赖箭头各自是独立的 item 类型,互不干扰。缩放时只需要调用 view 的 scale,所有 item 自动跟随。
常见做法是把场景坐标系的 X 轴映射成时间,Y 轴映射成任务行号。这样“某个时间点”和“某个像素位置”之间就是一个线性换算,源码里通常封装成一个 TimeAxis 类专门管这件事。
2.2 目录结构与模块职责
这份源码的目录大致是这样组织的:
GanttChart/
├── gantt/
│ ├── ganttview.h/cpp # 视图,负责缩放、滚动、坐标换算
│ ├── ganttscene.h/cpp # 场景,管理所有 item 的增删
│ ├── ganttitem.h/cpp # 任务条 item,处理拖拽和选中
│ ├── timeaxis.h/cpp # 时间轴,刻度与像素的换算
│ ├── dependencyitem.h/cpp # 依赖连线 item
│ └── ganttmodel.h/cpp # 数据模型,任务列表与依赖关系
├── widgets/
│ ├── mainwindow.h/cpp # 主窗口,工具栏与视图容器
│ └── taskeditor.h/cpp # 任务编辑对话框
└── main.cpp
ganttmodel 是纯数据层,不依赖任何图形类,任务用结构体存:id、名称、开始时间、工期、依赖的前置任务 id 列表。ganttscene 拿到 model 后,为每个任务创建一个 ganttitem,为每条依赖创建一个 dependencyitem。ganttview 负责把 scene 装进来,并处理滚轮缩放和右键菜单。
这种分层的好处是:你想换成从数据库读任务,只改 model 的加载逻辑;你想换一套任务条样式,只改 ganttitem 的 paint。两边不会互相牵连。
2.3 时间轴换算:整个甘特图的数学基础
时间轴换算是所有绘制和交互的前提。源码里 TimeAxis 一般提供两个核心方法: dateToX(QDateTime) 和 xToDate(qreal) 。内部维护一个起始时间和一个“每天多少像素”的比例因子。
// timeaxis.h 核心接口示意
class TimeAxis {
public:
// 设置图表起始日期和每日像素宽度
void setRange(const QDateTime &start, int pixelsPerDay);
// 日期转场景 X 坐标
qreal dateToX(const QDateTime &dt) const;
// 场景 X 坐标反解成日期
QDateTime xToDate(qreal x) const;
// 根据视图宽度决定刻度粒度:日/周/月
void updateTickGranularity(qreal viewWidth);
private:
QDateTime m_startDate;
int m_pixelsPerDay = 40;
};
dateToX 的实现就是 m_startDate.daysTo(dt) * m_pixelsPerDay ,反过来 xToDate 用 m_startDate.addDays(x / m_pixelsPerDay) 。参数 m_pixelsPerDay 直接决定图表的疏密,缩放时改的就是它,或者改 view 的 transform。注意这里用 daysTo 会丢掉一天内的小时精度,如果任务工期精确到小时,需要换成 secsTo 再除以 86400 换算成天。
刻度粒度那块是个容易忽略的点:视图拉得很宽时按天画刻度,缩得很窄时还按天画就会糊成一片,所以要按 viewWidth 动态切到周或月。源码里 updateTickGranularity 就是干这个的,阈值一般取“每天像素小于 15 就切周,小于 5 就切月”。
3. 跑起来:编译配置与最小可运行示例
3.1 环境与 .pro 配置
这份源码基于 Qt Widgets,Qt5 和 Qt6 都能编。用 qmake 的话,.pro 文件关键就几行:
QT += core gui widgets
CONFIG += c++17
TARGET = GanttChart
TEMPLATE = app
SOURCES += main.cpp \
gantt/ganttview.cpp \
gantt/ganttscene.cpp \
gantt/ganttitem.cpp \
gantt/timeaxis.cpp \
gantt/dependencyitem.cpp \
gantt/ganttmodel.cpp \
widgets/mainwindow.cpp \
widgets/taskeditor.cpp
HEADERS += gantt/ganttview.h \
gantt/ganttscene.h \
gantt/ganttitem.h \
gantt/timeaxis.h \
gantt/dependencyitem.h \
gantt/ganttmodel.h \
widgets/mainwindow.h \
widgets/taskeditor.h
如果你用 CMake,对应的是 find_package(Qt6 COMPONENTS Widgets REQUIRED) 加 target_link_libraries(GanttChart PRIVATE Qt6::Widgets) 。Qt5 就把 6 换成 5。这里没有用到 Qt Charts 或 Qt Quick,纯 Widgets,依赖很干净,不需要额外装模块。
3.2 从 model 到 scene 的装配流程
跑起来的关键是把数据灌进 model,再让 scene 根据 model 建 item。主窗口初始化大致是这么个顺序:
// mainwindow.cpp 初始化片段
void MainWindow::initGantt()
{
// 1. 准备数据模型
m_model = new GanttModel(this);
m_model->addTask(1, "需求评审", QDateTime(QDate(2024,6,1)), 3, {});
m_model->addTask(2, "接口设计", QDateTime(QDate(2024,6,4)), 4, {1});
m_model->addTask(3, "编码实现", QDateTime(QDate(2024,6,8)), 10, {2});
// 2. 创建场景并绑定模型
m_scene = new GanttScene(this);
m_scene->setTimeAxis(m_axis);
m_scene->loadFromModel(m_model); // 内部为每个任务建 GanttItem
// 3. 视图装载场景
m_view = new GanttView(this);
m_view->setScene(m_scene);
setCentralWidget(m_view);
}
addTask 的参数依次是任务 id、名称、开始时间、工期天数、前置依赖 id 列表。 loadFromModel 是核心装配点,它遍历 model 里的任务,用 TimeAxis 把开始时间和工期换算成 item 的矩形区域,再根据依赖关系生成连线。注意依赖必须在所有任务都建好之后再画,否则前置任务 item 还不存在,连线会找不到锚点。
3.3 编译与运行
命令行下就是标准的 qmake 流程:
qmake GanttChart.pro
make -j4
./GanttChart
Windows 上用 mingw32-make 或 nmake 替代 make。如果报 “cannot find -lQt5Widgets”,说明 Qt 的库路径没进环境变量,用 Qt 自带的命令行终端跑就行。跑起来后主窗口应该显示三条带依赖箭头的任务条,滚轮可以缩放,拖动任务条右边缘能改工期。
提示:第一次跑如果任务条挤在左上角,多半是 TimeAxis 的起始日期没设,默认值可能是 1970 年,导致所有任务都堆在最左边。
4. 核心模块拆解:任务条绘制与拖拽交互
4.1 GanttItem 的绘制逻辑
任务条是整个控件里交互最重的 item。它的 paint 方法要画背景、文字、进度,还要根据选中状态换颜色。
// ganttitem.cpp 绘制核心
void GanttItem::paint(QPainter *p, const QStyleOptionGraphicsItem *opt, QWidget *)
{
QRectF r = rect();
// 选中态用高亮色,普通态用主题色
QColor fill = isSelected() ? QColor(0x2d7ff9) : QColor(0x5b9bd5);
p->setBrush(fill);
p->setPen(Qt::NoPen);
p->drawRoundedRect(r, 4, 4);
// 进度条:按 m_progress 比例覆盖一层深色
if (m_progress > 0.0) {
QRectF pr = r;
pr.setWidth(r.width() * m_progress);
p->setBrush(QColor(0x1a5fb4));
p->drawRoundedRect(pr, 4, 4);
}
// 任务名,超出宽度就省略
p->setPen(Qt::white);
p->drawText(r.adjusted(6, 0, -6, 0),
Qt::AlignVCenter | Qt::AlignLeft,
p->fontMetrics().elidedText(m_name, Qt::ElideRight, int(r.width()) - 12));
}
m_progress 是 0 到 1 的浮点数,代表完成度。 elidedText 负责在任务条太窄时把名字截断成“需求评...”,避免文字溢出到别的条上。绘制顺序很重要:先画底色,再画进度,最后画文字,反了文字会被盖住。
4.2 拖拽改工期与移动任务
拖拽分两种:拖右边缘改工期,拖中间整体平移。判断依据是鼠标按下时距离右边缘的像素。
// ganttitem.cpp 鼠标事件
void GanttItem::mousePressEvent(QGraphicsSceneMouseEvent *e)
{
// 距离右边缘 8 像素内视为“改工期”手柄
m_resizing = (rect().right() - e->pos().x()) < 8;
m_dragStartX = e->scenePos().x();
m_origRect = rect();
QGraphicsItem::mousePressEvent(e);
}
void GanttItem::mouseMoveEvent(QGraphicsSceneMouseEvent *e)
{
qreal dx = e->scenePos().x() - m_dragStartX;
if (m_resizing) {
// 改宽度,最小保留一天
qreal newW = qMax(m_axis->dateToX(m_axis->xToDate(0).addDays(1)),
m_origRect.width() + dx);
setRect(0, 0, newW, m_origRect.height());
} else {
// 整体平移,同时更新开始时间
setPos(m_origRect.x() + dx, m_origRect.y());
}
e->accept();
}
m_resizing 这个标志在按下时确定,移动过程中不再变。改工期时用 qMax 保证最小宽度不小于一天,否则用户能把任务拖成一条线,数据上工期变成 0 天,后续依赖计算会出问题。整体平移时改的是 item 的 pos,但真正落库要在 mouseReleaseEvent 里把新的 x 坐标反解成日期,写回 model。
4.3 依赖连线的锚点计算
依赖箭头从 A 的右边缘连到 B 的左边缘。难点在于两个 item 可能不在同一行,连线要拐弯。
// dependencyitem.cpp 计算路径
void DependencyItem::updatePath()
{
if (!m_from || !m_to) return;
// 起点:前置任务右边缘中点
QPointF start = m_from->mapToScene(m_from->rect().topRight() + QPointF(0, m_from->rect().height()/2));
// 终点:后置任务左边缘中点
QPointF end = m_to->mapToScene(m_to->rect().topLeft() + QPointF(0, m_to->rect().height()/2));
QPainterPath path(start);
qreal midX = start.x() + 12; // 先向右伸出一小段
path.lineTo(midX, start.y());
path.lineTo(midX, end.y()); // 竖直拐到目标行
path.lineTo(end.x(), end.y()); // 再水平连到目标
setPath(path);
}
mapToScene 把 item 局部坐标转成场景坐标,这样不管任务条怎么移动,连线都能跟着更新。 midX 那个 12 像素的伸出量是为了让箭头不要贴着任务条,视觉上更清楚。如果两个任务在同一行,中间两段会退化成一条直线,逻辑依然成立。
注意:依赖连线必须在任务条移动后调用 updatePath,否则拖完任务箭头还停在原地。常见做法是在 GanttItem 的 itemChange 里监听位置变化,通知所有关联的 dependencyitem 刷新。
5. 避坑与排查:甘特图开发里最容易翻车的几处
5.1 任务条拖拽后数据没同步
现象是界面上任务条挪了位置,但保存或刷新后弹回原位。原因是拖拽只改了 item 的 pos 或 rect,没有在 mouseReleaseEvent 里把新坐标反解成日期写回 model。解决方式是在释放事件里调用 m_axis->xToDate(pos().x()) 得到新开始时间,再 m_model->updateTask(id, newStart, newDuration) ,最后触发一次 scene 重绘。
5.2 缩放后刻度文字重叠
现象是滚轮缩小后,时间轴上的日期挤成一团黑。原因是刻度粒度没有随缩放动态调整,一直按天画。解决办法是在 GanttView 的 wheelEvent 里,缩放后调用 m_axis->updateTickGranularity(viewport()->width()) ,让 TimeAxis 根据当前每天像素数决定画日、周还是月刻度,并重新生成刻度 item。
5.3 依赖连线在任务删除后变成野指针
现象是删掉一个任务后程序崩溃或画出乱线。原因是 dependencyitem 里存了 GanttItem 的裸指针,任务删除时 item 被销毁,指针悬空。常见做法是用 QPointer 包一层,或者在 GanttScene 删除任务时先遍历所有 dependencyitem,把引用了该任务的连线一并删掉,再删任务本身。
5.4 大量任务时滚动卡顿
现象是任务超过几百条后拖动滚动条明显掉帧。原因是每个任务条都是独立 item,场景重绘时全部走一遍 paint。优化方向是开启 setViewportUpdateMode(QGraphicsView::SmartViewportUpdate) ,只重绘可见区域;再进一步可以给 item 设置 setCacheMode(QGraphicsItem::DeviceCoordinateCache) ,把不常变的绘制结果缓存成位图。
5.5 时间精度丢失导致工期算错
现象是跨天的任务工期总是差一天。原因是 daysTo 返回的是整数天,如果开始时间是下午、结束时间是次日上午,算出来可能少一天。解决方式是内部统一用秒或毫秒存时间戳,换算时用 secsTo / 86400.0 保留小数,显示时再取整。工期字段建议用浮点天数,别用 int。
6. 二次开发:把这份源码改成你自己的排程控件
拿到这份源码后,最常改的三个方向是数据源、样式和交互扩展。数据源方面,ganttmodel 现在是内存结构,你可以把它换成从 SQLite 或 JSON 加载。我一般会在 model 里加一个 loadFromJson(const QJsonArray&) ,字段名和 addTask 的参数对齐,这样外部系统导出的排期数据能直接灌进来。样式方面,任务条的颜色、圆角、进度条颜色都集中在 GanttItem::paint 里,想换主题就抽一个 StyleConfig 结构体,把颜色和尺寸参数外置。交互扩展方面,比较常见的是加“双击编辑任务”和“右键删除”。双击可以在 GanttItem 的 mouseDoubleClickEvent 里发一个自定义信号,主窗口收到后弹 TaskEditor 对话框,改完再写回 model。
验证改动是否正确的办法很土但有效:改完数据源后,先只加载一条任务,看它落在时间轴上的位置对不对;再加依赖,看箭头锚点准不准;最后把任务数拉到 200 条,滚一遍看卡不卡。这三步走完,基本能覆盖 90% 的回归问题。
有个细节值得单独说:如果你要做“任务条按状态变色”,别在 paint 里写一堆 if-else,而是在 GanttItem 里存一个状态枚举,paint 时查一张颜色表。这样加状态只改表,不动绘制逻辑。我早期就是 if-else 堆了七八个分支,后来加一个状态要改三处,血泪经验。
从那以后我每次改这类图形控件,都强制先跑一遍“单任务 → 加依赖 → 压测 200 条”的流程,确认坐标换算和刷新逻辑没被破坏再往下做。希望这份拆解能帮你少走点弯路,把这份 Qt 甘特图源码真正用起来。
240



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



