Qt原生甘特图控件：支持拖拽调度、资源联动与冲突检测-平芜编程栈

简介：本资源是一份基于Qt框架实现甘特图的完整C++源码工程，面向具备基础Qt开发经验的中初级开发者，解决项目管理类应用中任务时间轴可视化与交互控制的核心需求。代码采用模块化设计，涵盖数据模型（Task结构体、QAbstractItemModel子类）、图形渲染（QGraphicsView/QGraphicsScene + QPainter定制绘制）、用户交互（拖拽修改工期、双击弹窗编辑）及时间计算（QDateTime驱动的时间约束逻辑），适用于桌面端跨平台项目调度工具开发。压缩包共12个文件，含5个头文件（.h）定义核心数据结构与对话框接口、4个源文件（.cpp）实现业务逻辑与绘图逻辑、1个Qt工程配置文件（.pro）、1个说明文本（.txt）及1个用户配置文件（.user），整体仅14KB，轻量易读。已有3109人学习下载，读者可直接编译运行，快速掌握Qt自定义图表组件的典型开发范式，包括信号槽驱动视图更新、图形项动态管理、时间轴缩放适配等关键实践要点。

1. 甘特图不是PPT动画：这是能拖拽调整工期、实时联动资源视图、嵌入工业调度系统的Qt原生控件

上周帮某高校实验室对接一个产线排程系统，对方拿Excel甘特图贴进汇报PPT——结果现场演示时，客户指着屏幕问：“这个任务能不能拖动改时间？改完下游依赖自动重排吗？工人A今天请假，谁来顶班？”——全场安静。后来我甩出这个Qt甘特图源码包：鼠标按住任务条左右拖，工期秒变；双击弹出资源分配面板，勾选“张工”“李工”，右侧资源热力图立刻染色；导出PDF时连横轴时间刻度都按实际工时（8:00-12:00,13:00-17:30）精准切分。它不渲染成图片，而是用QGraphicsView+自定义QGraphicsItem构建的原生控件，所有交互走Qt事件循环，没套任何Web View或第三方图表库。适合嵌入已有Qt桌面端MES/SCADA系统，也适合作为毕业设计核心模块——代码全在src/下，无隐藏依赖，C++11起步，qmake可直接编译。如果你正卡在“甘特图只能看不能调”“想改样式但SVG改不动”“Qt Widgets画不出专业排程界面”这三堵墙之间，这个包就是凿墙的钎子。

2. 架构拆解：从QGraphicsScene到任务依赖图的三层数据映射

这个项目没用QChart或QCustomPlot，而是用Qt最底层的图形视图框架（Graphics View Framework）硬刚。核心就三块：数据模型层（TaskModel）、视图层（GanttView）、交互层（GanttItem）。它们不是松散耦合，而是用信号槽强绑定——比如你拖动一个任务条，GanttItem发信号给TaskModel更新start/end时间，TaskModel立刻广播changed()信号，GanttView收到后重绘整个时间轴。这种设计牺牲了点开发速度，换来的是毫秒级响应和绝对可控的渲染逻辑。

2.1 数据模型层：TaskModel如何承载真实项目约束

TaskModel继承自QAbstractItemModel，但它没走标准的行列树结构，而是用QVector 存任务，用QMap<QString, QVector >按阶段分组。每个Task结构体里藏着关键字段：

struct Task { QString id; // 任务唯一ID，用于跨模块引用 QString name; // 显示名称（支持中文） QDateTime start; // 实际开始时间（含日期+时分） QDateTime end; // 实际结束时间（含日期+时分） int progress; // 进度百分比（0-100） QStringList dependencies; // 依赖任务ID列表，如{"TASK-001", "TASK-002"} QStringList resources; // 分配资源ID，如{"WORKER-A", "MACHINE-X"} QColor color; // 任务条颜色（默认按阶段生成） };

提示：dependencies字段是甘特图变“智能”的关键。TaskModel内部维护一个DAG（有向无环图），每次调用updateTask()时会触发拓扑排序校验——如果TASK-002依赖TASK-001，但你把TASK-001拖到TASK-002之后，模型会自动拒绝这次修改并返回错误码。这个逻辑在TaskModel::validateDependency()里，不是靠前端提示，而是从数据源头掐断非法操作。

2.2 视图层：GanttView如何把时间轴变成可缩放的坐标系

GanttView继承自QGraphicsView，但它重写了wheelEvent()和mousePressEvent()实现时间轴缩放和平移。关键在于它把“时间”映射成“像素”：

// GanttView.cpp 中的时间转像素计算 int GanttView::timeToX(const QDateTime &dt) const { // 计算dt距离视图左边界起始时间的小时数 qint64 hours = startDateTime.secsTo(dt) / 3600; // 每小时固定占多少像素（zoomLevel决定） return static_cast<int>(hours * pixelsPerHour); } // 缩放时动态调整pixelsPerHour void GanttView::setZoomLevel(double level) { pixelsPerHour = 20.0 * level; // level=1.0时，每小时20px；level=2.0时，每小时40px scene()->update(); // 强制重绘整个场景 }

这里有个血泪经验：别用QDateTime::daysTo()算天数再乘以像素/天——工业排程常需精确到分钟（比如“设备校准：14:30-15:15”），必须用secsTo()转成秒再除以3600得小时数，否则缩放到分钟级时会出现整小时跳变。

2.3 交互层：GanttItem如何实现“拖拽即生效”的手感

每个任务条都是一个独立的GanttItem（继承自QGraphicsRectItem），但它重写了mouseMoveEvent()：

// GanttItem.cpp void GanttItem::mouseMoveEvent(QGraphicsSceneMouseEvent *event) { if (m_dragState == DragStart) { // 记录初始位置和时间偏移 m_startPos = event->scenePos(); m_startTime = m_task->start; m_dragState = Dragging; } else if (m_dragState == Dragging) { // 将鼠标移动像素转回时间偏移 double dx = event->scenePos().x() - m_startPos.x(); QDateTime newStart = m_startTime.addSecs( static_cast<qint64>(dx / view()->pixelsPerHour * 3600) ); // 调用模型更新（非直接改m_task！） view()->model()->updateTaskStartTime(m_task->id, newStart); } }

注意：updateTaskStartTime()是模型层接口，它内部会校验新时间是否合法（比如不早于项目开始日、不晚于截止日），校验失败则抛出异常，GanttItem捕获后会回滚视觉位移——这就是为什么你拖到边界时任务条“弹”回来，而不是卡死。

3. 编译与运行：qmake一步到位，但这些配置项决定你能否看到真实效果

项目用qmake管理，没有CMakeLists.txt。根目录下只有一个gantt.pro文件，但里面藏着几个影响成败的关键变量。别急着qmake && make，先确认这三件事。

3.1 Qt版本与模块依赖：5.12+是底线，Widgets必选

gantt.pro第一行写着：

QT += core widgets gui printsupport

这意味着它不兼容Qt6（Qt6把widgets拆成单独模块且API有变），也不兼容Qt5.9以下（QDateTime::addSecs()在5.9前对负数支持不稳定）。我实测过：在Qt5.12.12 + MinGW7.3环境下编译通过；若用MSVC2019，需在pro里加：

win32-msvc { CONFIG += c++11 QMAKE_CXXFLAGS += /std:c++17 }

否则std::optional相关代码报错。

3.2 时间轴范围配置：别让程序启动后只显示“1970年1月1日”

项目默认时间轴从当前时间往前推7天、往后推30天。但如果你双击运行，发现横轴全是1970年——那是因为main.cpp里这行被注释了：

// MainWindow.cpp 第42行（默认注释状态） // view->setTimeRange(QDateTime::currentDateTime().addDays(-7), // QDateTime::currentDateTime().addDays(30));

必须取消注释，并根据你的业务改数字。比如做月度生产计划，改成：

view->setTimeRange(QDateTime(QDate::currentDate().year(), QDate::currentDate().month(), 1), QDateTime(QDate::currentDate().addMonths(1).year(), QDate::currentDate().addMonths(1).month(), 1));

3.3 中文显示与字体：微软雅黑不是默认选项

Qt默认用系统等宽字体（Linux是DejaVu Sans Mono），中文会糊成方块。解决方案在MainWindow.cpp的构造函数末尾：

// 添加中文字体支持 QFont font("Microsoft YaHei", 9); // Windows // QFont font("Noto Sans CJK SC", 9); // Linux // QFont font("PingFang SC", 9); // macOS font.setHintingPreference(QFont::PreferFullHinting); view->setFont(font);

注意：macOS下PingFang SC可能不存在，建议先用QFontDatabase::families()打印可用字体列表，再选一个带中文的。

4. 避坑指南：那些让你编译成功却运行崩溃的玄学问题

这个项目代码质量高，但Qt图形视图框架的某些行为像黑匣子。以下是我在三台不同环境（Win10/Ubuntu20.04/macOS12）上踩出的5个真实坑，按发生频率排序：

4.1 现象：程序启动后甘特图空白，控制台输出"QPainter::begin: Widget painting can only begin as a result of a paintEvent"

原因：GanttView的scene()未正确设置，或QGraphicsScene在QGraphicsView构造前被析构。常见于MainWindow中先new QGraphicsScene()再new GanttView()，但没调用setScene()。
解决：检查MainWindow.cpp中setupUi()后的初始化顺序，确保：

m_scene = new QGraphicsScene(this); m_view = new GanttView(m_scene, this); // 构造时传scene m_view->setScene(m_scene); // 再显式设置一次（双重保险）

4.2 现象：拖拽任务条时界面卡死，CPU飙到100%

原因：TaskModel::data()函数里用了QDateTime::toString("yyyy-MM-dd hh:mm")格式化时间，而该函数在每次重绘时被调用数百次（每个格子都要取时间文本）。字符串格式化是重操作。
解决：在Task结构体中预存格式化字符串：

struct Task { // ...其他字段 mutable QString displayTime; // mutable允许const函数修改 QString getDisplayTime() const { if (displayTime.isEmpty()) { displayTime = start.toString("MM-dd hh:mm") + " → " + end.toString("MM-dd hh:mm"); } return displayTime; } };

4.3 现象：双击任务条弹出编辑窗口，但修改后进度条不更新

原因：编辑窗口用QDialog模态弹出，阻塞了事件循环，导致TaskModel::dataChanged()信号发出后，GanttView的dataChanged槽函数来不及执行。
解决：在编辑窗口的accept()里，不直接调用model->updateTask()，而是用QMetaObject::invokeMethod()延后执行：

// EditDialog.cpp void EditDialog::accept() { // ...保存数据到task对象 QMetaObject::invokeMethod(model, [this](){ model->updateTask(m_task); }, Qt::QueuedConnection); // 关键：用队列连接，等事件循环空闲时执行 QDialog::accept(); }

4.4 现象：导出PDF时时间轴文字被截断，或任务条高度压缩成一条线

原因：QPrinter的DPI设置与屏幕DPI不一致，导致QGraphicsScene::render()计算尺寸错乱。
解决：导出PDF前强制设置打印机DPI为96（匹配屏幕）：

QPrinter printer(QPrinter::HighResolution); printer.setOutputFormat(QPrinter::PdfFormat); printer.setPaperSize(QPrinter::A4); printer.setResolution(96); // 关键！设为96而非默认的300

4.5 现象：在高DPI屏幕（如MacBook Pro）上，任务条模糊、文字发虚

原因：Qt5.14+默认启用高DPI适配，但QGraphicsView的setViewportUpdateMode()未设为FullViewportUpdate，导致缩放后纹理未重采样。
解决：在GanttView构造函数中添加：

setViewportUpdateMode(FullViewportUpdate); setRenderHint(QPainter::Antialiasing, true); setRenderHint(QPainter::TextAntialiasing, true);

5. 核心模块改造：给甘特图加上资源冲突检测与自动重排

默认源码只做单任务拖拽，但真实产线调度要解决“张工同时被3个任务占用”的冲突。我基于原架构加了资源冲突检测模块，不到200行代码，就能让甘特图从“静态展示”升级为“智能调度助手”。

5.1 冲突检测引擎：ResourceConflictDetector类设计

新建src/core/resourceconflictdetector.h，核心逻辑是扫描所有任务，按资源ID分组，再检查同一资源下的时间重叠：

class ResourceConflictDetector { public: struct Conflict { QString resourceId; QString taskAId; QString taskBId; QDateTime overlapStart; QDateTime overlapEnd; }; static QVector<Conflict> detect(const QVector<TaskPtr> &allTasks) { QMap<QString, QVector<TaskPtr>> resourceMap; // 按资源ID分组 for (const auto &task : allTasks) { for (const QString &res : task->resources) { resourceMap[res].append(task); } } QVector<Conflict> conflicts; for (auto it = resourceMap.begin(); it != resourceMap.end(); ++it) { const auto &tasks = it.value(); // 两两比较时间重叠 for (int i = 0; i < tasks.size(); ++i) { for (int j = i + 1; j < tasks.size(); ++j) { const auto &a = tasks[i]; const auto &b = tasks[j]; // 计算时间重叠区间 QDateTime start = qMax(a->start, b->start); QDateTime end = qMin(a->end, b->end); if (start < end) { // 有重叠 conflicts.append({it.key(), a->id, b->id, start, end}); } } } } return conflicts; } };

5.2 在拖拽时实时触发检测与干预

回到GanttItem::mouseReleaseEvent()，在任务时间更新后插入检测：

void GanttItem::mouseReleaseEvent(QGraphicsSceneMouseEvent *event) { if (m_dragState == Dragging) { // ...原有更新逻辑 bool success = view()->model()->updateTaskStartTime(m_task->id, newStart); if (success) { // 新增：检测资源冲突 auto conflicts = ResourceConflictDetector::detect( view()->model()->getAllTasks() ); if (!conflicts.isEmpty()) { // 弹窗警告（可选：自动微调避免冲突） showConflictWarning(conflicts); // 或者更激进：自动将冲突任务后移 // auto adjusted = autoResolveConflict(conflicts.first()); // view()->model()->updateTaskStartTime(adjusted.taskId, adjusted.newStart); } } } QGraphicsRectItem::mouseReleaseEvent(event); }

5.3 可视化冲突：在任务条上叠加红色警示图标

在GanttItem::paint()中，当检测到本任务有冲突时，绘制小红三角：

void GanttItem::paint(QPainter *painter, const QStyleOptionGraphicsItem *, QWidget *) { // ...原有绘制逻辑 if (m_hasConflict) { // 由模型层通知此任务有冲突 painter->save(); painter->setPen(Qt::red); painter->setBrush(Qt::red); // 在任务条右上角画小三角 QPointF points[3] = { rect().topRight() + QPointF(-5, 5), rect().topRight() + QPointF(-10, 5), rect().topRight() + QPointF(-7.5, 0) }; painter->drawPolygon(points, 3); painter->restore(); } }

从那以后我每次给调度系统加新功能，都强制走一遍“冲突检测-可视化-自动修复”三步验证：先用ResourceConflictDetector::detect()跑全量数据看是否漏检；再在UI上拖拽制造冲突，确认红标出现；最后写个测试用例，模拟100个任务随机分配资源，验证自动重排后冲突数归零。这套流程让我避开了三次上线后被半夜叫醒修bug的灾难。希望帮到你。

本文还有配套的精品资源，点击获取