企业官网建设流程全解析

做项目管理工具绕不开甘特图，做甘特图绕不开一条能快速定位到具体任务的导航栏。我最近在维护一套 Qt 桌面客户端，里面有个内部代号叫 G06 的导航栏组件，专门用来配合项目甘特图做导航联动。说白了就是左侧一棵项目任务树，右侧一整条时间轴甘特图，你在左边点任何一个任务，右侧视图立刻把对应的任务条滚到可见区域并高亮；反过来在甘特图上选中某个任务，左侧导航栏也会同步展开并选中对应的节点。这套交互在大型项目排期里非常实用，尤其适合做研发管理、制造排产、工程计划这类多层级任务系统。

G06 不是那种独立展示的静态图表，它强调的是“导航”。导航栏和甘特图之间的联动、点击定位、滚动同步、层级折叠时的视口修正，这些才是真正考验功底的地方。写这篇文章，就是想把我这大半年在 G06 上拆过的问题、填过的坑、以及最后沉淀下来的实现方案，完整讲一遍。内容不绕弯，直接给你看设计思路、关键代码、联动逻辑和排查经验，适合用 Qt 写项目管理系统、正在设计任务展示组件的开发者参考。

1. 整体设计思路：为什么导航栏和甘特图必须绑在一起

1.1 从项目管理场景的痛点说起

我们内部之前有个老版本模块，甘特图是整块绘制的，左边没有树，右边直接画时间条。任务一多就乱：几十个 WBS 节点展开后，几百条任务叠在一个滚动区域里，用户想找一个三天前开始的任务，得眼睛贴着屏幕一行一行扫。后来加了左侧独立树，但右侧甘特图完全不跟随，树滚动到第 50 层，右侧还停在第一层，两个视图各滚各的，体验更差。

用户反馈最集中的问题其实只有一个：给我一个稳定的参照物，让我知道当前在看哪一层、哪条任务，并且能一键跳过去。

这里的“参照物”就是导航栏。它不是简单的树形列表，而是甘特图的一个纵向索引。项目管理里任务天然有层级关系，比如“项目阶段 -> 工作包 -> 具体任务 -> 子任务”，这种层级关系用树形导航栏表达最自然，而甘特图的时间条也带着上下层级坐标。把这两者的行坐标做严格映射，就能做到点击任意导航项，甘特图滚动到对应任务条。

1.2 G06 的定位与设计目标

G06 的设计目标拆开看，其实就四件事：

• 纵向对齐：导航栏每一行的显示顺序、层级缩进、展开状态，必须和甘特图每一行的任务条严格对齐。这是整个联动的前提。
• 点击定位：在导航栏点击某个节点，甘特图自动滚动到对应行并高亮任务条；在甘特图点击任务条，导航栏自动将对应节点展开、选中、并保证它在可视区域内。
• 折叠保持：导航栏里父节点折叠后，甘特图对应的子任务行要一起隐藏，不能出现“左边没显示，右边还画着”的情况。
• 性能可控：几千个节点时，不管是树刷新、甘特图局部更新还是滚动同步，交互不能有明显的卡顿。

围绕这四条，我最终选用了一套很朴素的方案：左侧用 QTreeView 做导航树，右侧用继承 QAbstractScrollArea 的自绘甘特视图，两者之间通过一个项目任务模型共享数据源，再通过滚动条信号、点击信号、一个坐标映射接口做联动。没用第三方控件，全部 Qt 原生扩展。

1.3 为什么是 QTreeView 加自定义绘制，而不是现成甘特控件

很多朋友第一反应是找个开源的甘特图控件，改一改就能用。我试过，常见的问题有三类：一是开源控件普遍把树和甘特图集成在一个大视图里，自定义列、自定义右键菜单、颜色规则都要在人家封装好的接口里塞，越塞越难受；二是大量任务时性能不稳定，局部更新困难；三是想和现有项目系统的数据模型解耦很麻烦。

G06 选择把导航树和甘特视图拆成两个独立控件，核心原因是职责分离。QTreeView 本身就是一棵现成的导航树，层级展开、缩进、图标、拖拽、排序都能直接用，没必要重画一遍。甘特图部分集成度低，自己画反而可控，时间刻度、任务条颜色、依赖箭头、今天线都可以按需定制。两者靠同一个 QAbstractItemModel 的索引映射保持沟通，工作量和坑都在可控范围。

2. 数据模型与视图映射：联动的底层基础

2.1 用一个统一模型同时给树和甘特图喂数据

为了让导航栏和甘特图的行严格对应，我让两侧共用同一个任务模型，这个模型继承 QAbstractItemModel，每个 QModelIndex 就是一条任务节点。模型里除了名称、层级、父节点这些常规字段，还提供三个甘特图必需的字段：计划开始日期、计划结束日期、进度百分比。业务树里还可以加负责人、前置任务等扩展字段。

模型层的设计有一个原则：视图永远不直接拿业务对象指针，只通过 QModelIndex 取数据。这样导航栏和甘特图都通过 data() 拿名称、日期、进度，传递时也只用 model index，不用裸指针。这样后续把数据源从内存列表换成数据库、换成远程接口，只需要改模型，两个视图的联动代码一行都不用动。

2.2 行标识和层级映射要提前约定好

联动的核心困难在于：同一个任务，在导航栏里的“行号”和甘特图里的“行坐标”其实不是一回事。导航栏显示的是整棵树展开后的节点顺序，而甘特图绘制任务条时也需要按这个顺序从上往下排。所以必须有一个统一的“展开行序号”概念。

我的做法是在模型里加一个方法：

int rowOfIndex(const QModelIndex& index) const; QModelIndex indexOfRow(int row) const;

这两个方法内部递归遍历整棵树，按深度优先顺序，把每个展开节点的顺序号算出来。顺序号就是甘特图任务条的 Y 方向坐标。每次导航栏节点展开、折叠、增删任务后，调用 invalidateRowIndexCache 清掉缓存，下一次联动时重新计算。

这里有一个很关键的点：甘特图绘制的行号必须和导航栏 QTreeView 的视觉行顺序一致，而不是和 QModelIndex 的 row 字段一致。QModelIndex 的 row 只是兄弟节点里的序号，和整棵树展开后的视觉位置差很远。如果谁在甘特图里直接用 index.row() 算 Y 坐标，层级一展开就会错位，我见过不少项目就是这么出 bug 的。

2.3 展开状态和折叠同步

导航栏折叠一个父节点时，右侧甘特图要立刻把对应的子任务行隐藏。QTreeView 的展开折叠状态由 setExpanded 控制，但甘特视图不知道这个状态。解决方案是监听导航栏的 expand/collapse 信号，然后让甘特图刷新并重新计算任务条布局。

更稳的做法是让模型自己维护展开状态。我在模型里给每个节点留了一个 isExpanded 标记，QTreeView 在展开折叠时通过 setExpanded 触发的数据发生变化，同时模型内部更新标记。甘特图重绘时直接查模型里的展开状态，来决定某个父节点下的子任务是否需要画。这样就算导航栏暂时不可见，甘特图也能独立判断哪些行应该显示，不会出现“树没展开但甘特图画了一堆子任务”的问题。

3. 核心细节解析：时间坐标、任务条绘制和命中检测

3.1 甘特图的时间轴是怎么换算的

时间轴是甘特图最容易被低估的部分。很多人一开始只画“从第一个任务开始到最后一个任务结束”，后来加任务、跨月、跨年就乱了。G06 的时间轴支持日、周、月三个刻度等级，我把它抽象成一个 TimelineScale 类：

class TimelineScale { public: QDate viewStart; // 视图可见起点 QDate viewEnd; // 视图可见终点 int pxPerDay; // 每像素代表多少天（含小数） int xForDate(const QDate& date) const; QDate dateForX(int x) const; };

xForDate 的计算很简单，就是 date 与 viewStart 的天数差乘以 pxPerDay。真正麻烦的是用户在缩放、平移、拖动时间轴后，viewStart 和 pxPerDay 的联动调整。我建议把 pxPerDay 设置成支持浮点，缩放时按比例改，平移时改 viewStart，保证横向滚动条的总宽度按总天数乘像素密度动态变化。

顶部的时间刻度绘制也要分三层。最上面是年份、中间是月份、最下面是日期或周。月份交界处网格线加粗，周末列背景色加深，今天列画一条特殊的红色竖线。这些都是细节，但直接影响使用体验。

3.2 任务条的绘制策略

任务条的绘制我是用 QPainter 在甘特视图的 viewport 上直接画的。每个任务画成一条圆角矩形，左边界对应开始日期，右边界对应结束日期。常用的附加信息包括：进度条覆盖在任务条内部、里程碑画成菱形、延迟任务画成橙色、前置关系画成带箭头的折线。

画任务条时有一个性能优化重点：只画可视区域内的任务，不要整场绘制所有任务。甘特视图的滚动范围很大，如果几百上千条任务全画一遍，CPU 白烧。我的做法是先用 rowOfIndex 拿到可视范围的顶部行和底部行，再根据 viewStart 和 viewEnd 拿到可视时间范围，只对这些范围内的任务条调 painter->drawRect。画之前先做矩形相交判断：

bool TaskBar::intersects(const QRect& visibleRect) const { return rect().intersects(visibleRect); }

这个判断在任务总数上万个时尤其重要，能直接省掉 80% 以上无效绘制。

3.3 命中检测：点击任务条为什么偶尔串行

甘特视图要响应用户点击，必须在 mousePressEvent 里从坐标反算出点击的是哪个任务。这里的关键是不要用“遍历所有任务判断坐标”的粗暴方法，而是先用 y 坐标反敲出视觉行号：

int clickedRow = viewport->mapFromGlobal(event->globalPos()).y() / rowHeight; QModelIndex index = model->indexOfRow(headerFirstVisibleRow + clickedRow);

拿到行号后，再遍历该行内的任务条，判断 x 是否落在开始日期和结束日期映射的横向区间内。这样每次点击最多只需判断几条任务，不会整个模型刷一遍。

我第一次实现时踩过一个坑：直接用 event->pos() 判断坐标，忘了 viewport 里还可能有一个表头高度偏移。甘特图顶部有时间刻度区，这个区域的高度如果为 30px，点击坐标必须先把表头高度减掉，再除以行高，否则总差 30px，点击行为看起来就是“偏了”。后来我把表头高度作为常量暴露出来，命中检测前统一减去。

3.4 滚动同步：左右两个滚动条的博弈

导航栏有自己的 QScrollBar，甘特视图也有自己的 QScrollBar。用户滚动任何一个，另一个都要跟着动。这里最难处理的是滚动手感，不能搞成两边都触发滚动事件，然后互相调用 setValue，形成循环。

我的方案是：

• 导航树的垂直滚动条 valueChanged 信号里，直接设置甘特视图的垂直滚动条值，并加一个 m_syncing 标志。
• 甘特视图的垂直滚动条 valueChanged 信号里，同样设置导航树的滚动条值。
• 在设置对方滚动条前，先判断 m_syncing 是否为真，为真就跳过，防止两个滚动条来回触发。

void GanttView::onNavScroll(int value) { if (m_syncing) return; m_syncing = true; verticalScrollBar()->setValue(value); m_syncing = false; }

水平方向一般不强制同步，因为导航栏的列宽是固定的，不需要跟甘特图的水平滚动联动。但甘特图的水平滚动条变化时要刷新视图，不能让任务条拖影。

4. 实操过程：从零把 G06 搭起来

4.1 工程结构和核心类的职责划分

我建议工程里至少分这几个文件，避免后续把导航和绘制逻辑搅在一起：

• ProjectTreeModel：任务树模型，提供树结构、日期字段、展开状态、行号映射。
• ProjectTreeView：左侧导航栏，基于 QTreeView，负责展开折叠、节点点击、当前项变化信号。
• GanttView：右侧甘特视图，继承 QAbstractScrollArea，负责时间轴、任务条、依赖线绘制，以及滚动、点击、缩放。
• NavigationController：联动控制器，把树和甘特图绑定，处理行号计算、滚动同步、点击定位。

有一种做法是把 NavigationController 的逻辑直接塞进主窗口，我试过，短期省事，但 MainWindow 会越来越肥，最后改一个行为都要在几百行的事件里找。还是单独抽一个类更清爽。

4.2 定义一个最小但完整的项目任务模型

模型类可以先按最小可用来设计：

struct TaskItem { QString name; QDate startDate; QDate endDate; float progress = 0.0f; int parentId = -1; QList<int> childIds; bool expanded = true; bool milestone = false; }; class ProjectTreeModel : public QAbstractItemModel { public: // 常规 QAbstractItemModel 接口 QModelIndex index(int row, int column, const QModelIndex& parent) const override; QModelIndex parent(const QModelIndex& child) const override; int rowCount(const QModelIndex& parent) const override; QVariant data(const QModelIndex& index, int role = Qt::DisplayRole) const override; // 甘特图扩展接口 QDate startDateOf(const QModelIndex& index) const; QDate endDateOf(const QModelIndex& index) const; int rowOfIndex(const QModelIndex& index) const; QModelIndex indexOfRow(int visualRow) const; QDate minDate() const; QDate maxDate() const; private: void rebuildRowCache(); QVector<TaskItem> m_items; QHash<QModelIndex, int> m_rowCache; // 按深度优先展开序缓存 };

在实现 data() 时，用 UserRole 返回 startDate、endDate、progress、milestone 四个角色，甘特图直接从 index 取，避免每次都要把 TaskItem 的日期再学一遍转换。模型里的 rowOfIndex 用缓存实现，第一次访问时递归遍历，之后每次变化后清缓存。

4.3 写出甘特图的核心绘制逻辑

GanttView 的核心是 paintEvent。我先把整个绘制流程拆成三个函数：

void GanttView::paintEvent(QPaintEvent* event) { QPainter painter(viewport()); painter.setRenderHint(QPainter::Antialiasing, true); drawTimeline(&painter); // 顶部时间刻度 drawGrid(&painter); // 背景网格线 drawTaskBars(&painter); // 任务条和依赖线 }

drawGrid 和 drawTaskBars 都要先算出可视矩形：

QRect visibleRect = viewport()->rect(); visibleRect.setTop(m_headerHeight); int firstRow = visibleRect.top() / m_rowHeight; int lastRow = visibleRect.bottom() / m_rowHeight;

然后在循环里只画 firstRow 到 lastRow 之间的行。任务条的颜色我用一个统一函数按任务状态返回，延迟、关键路径、里程碑各有各的颜色规则，集中管理，后续改需求时只动一个函数。

里程碑绘制稍微特殊：不是矩形条，而是一个菱形。位置按开始日期取，x 坐标对应日期中点，y 坐标对应行中点。画菱形时注意，很多人直接拿 painter->drawPolygon 画，坐标一偏就显得歪，建议用 QPolygonF 基于行矩形中心点生成四个顶点。

4.4 绑定导航栏点击和甘特图滚动

联动控制器负责把“点击导航节点”翻译成“甘特图滚动到该行”。核心逻辑如下：

void NavigationController::onTreeClicked(const QModelIndex& index) { if (!index.isValid()) return; int visualRow = m_model->rowOfIndex(index); int scrollTarget = visualRow * m_gantt->rowHeight(); m_gantt->verticalScrollBar()->setValue(scrollTarget); m_gantt->setHighlightIndex(index); // 让树滚动到当前项，保证当前项可见 m_tree->scrollTo(index, QAbstractItemView::PositionAtCenter); }

注意这里计算 scrollTarget 用的是“视觉行号乘行高”，不是简单的“当前 index.row() 乘行高”。如果层级很深，index.row() 只是兄弟节点序号，直接乘行高会滚错位置。

反向联动是甘特图中点击某个任务条后，导航树展开对应父节点并选中：

void GanttView::onTaskClicked(const QModelIndex& taskIndex) { QModelIndex parent = taskIndex.parent(); while (parent.isValid()) { m_tree->setExpanded(parent, true); parent = parent.parent(); } m_tree->setCurrentIndex(taskIndex); m_tree->scrollTo(taskIndex); }

从测试数据来看，这两个联动加起来不足 100 行代码，但能做到这一层，前提是前面项目模型的 rowOfIndex 和展开状态处理得够扎实。

4.5 在主窗口里把组件拼起来

最后做一个简单的集成示例，NavigationController 初始化后，把树和甘特视图放到一个 QSplitter 里。左右分栏比例按 3:7 分配，导航栏最小宽度 240px，甘特视图最小宽度 600px。

ProjectTreeModel* model = new ProjectTreeModel(this); model->loadDemoProject(); ProjectTreeView* tree = new ProjectTreeView(this); tree->setModel(model); tree->setHeaderHidden(true); GanttView* gantt = new GanttView(this); gantt->setModel(model); NavigationController* nav = new NavigationController(this); nav->bind(tree, gantt, model); QSplitter* splitter = new QSplitter(this); splitter->addWidget(tree); splitter->addWidget(gantt); splitter->setStretchFactor(0, 3); splitter->setStretchFactor(1, 7); setCentralWidget(splitter);

到这里，一个能用的 G06 骨架就出来了。实际项目中还会加右键菜单、任务筛选、拖拽调整日期、甘特图内部拖动依赖线连线等功能，但核心的导航联动逻辑已经完整。

5. 常见问题与排查技巧实录

5.1 重绘闪烁和局部刷新问题

刚开始写甘特图时，我偷懒在 paintEvent 里全量重绘，任务少时看不太出来，任务一多，滚动时整个视图闪烁，尤其时间轴区域特别明显。排查后发现是两个原因：一是事件里有系统背景擦除，二是滚动时没有开启局部更新。

解决办法两件事：

• 在构造函数里设置setAttribute(Qt::WA_OpaquePaintEvent)，避免 Qt 在 paintEvent 前先擦除背景。
• paintEvent 里用 QPainter 的 clipRect 限制在脏矩形区域内绘制。滚动时只重绘新暴露的区域。

QPainter painter(viewport()); painter.setClipRect(event->rect());

5.2 滚动条联动失灵或闪烁

联动出问题的典型现象是：拖动导航栏滚动条，甘特图跟了一半，松手后弹回去；或者两个滚动条来回抖。

我排查后基本锁定在信号死循环上。两个滚动条互相 setValue，会触发对方的 valueChanged，如果不加互斥标志，就会无限循环。还有一种情况是滚动手感“发飘”，是因为没有在 setValue 之前判断目标值和当前值是否一样。

if (targetScrollValue == verticalScrollBar()->value()) return;

有效解决后，还要记得在 tree 和甘特图的展开/折叠、任务增删、行高变化之后，重新对齐两者的滚动值，否则本来同步着，用户一展开父节点，右边行数变多，两边的视觉位置就错位了。

5.3 点击命中不准：任务条偏了半个行高

前文提到过表头高度偏移问题。还有一个常见坑是坐标系用了错的对象。甘特图里如果直接使用event->pos()，这个坐标是相对于 viewport 的，但如果你在计算时拿到的是 widget 的坐标，或者用了event->globalPos()但没有做 viewport 映射，都会偏。

我的统一写法：

QPoint localPos = viewport()->mapFromGlobal(event->globalPos()); int row = (localPos.y() - m_headerHeight) / m_rowHeight;

另外建议把 rowHeight 定义成 const int，然后所有用到行高的地方都引用同一个变量，不要一会儿乘 30，一会儿乘 32。行高一旦修改，命中检测、滚动目标、绘制坐标全部跟着改，变量统一就能少踩一半的坑。

5.4 大数据量下的卡顿优化

当任务达到五千条以上，主要瓶颈有三个：行号缓存、任务条绘制、展开折叠时模型刷新。行号映射我第一次是用递归遍历每访问一次就 O(n) 算一次，后来加了缓存，只有结构变化时才重建，速度从慢到不可用变成毫秒级。任务条绘制走了可视区域裁剪后，单帧重绘只花一到两毫秒。展开折叠时如果动不动就调用 beginResetModel 全量刷新，也会卡，后来改成按局部行插入移除的信号，只刷新相关子树的导航行号和甘特图局部行。

还有一个容易忽略的性能杀手是日期换算。每个任务在绘制时要根据 xForDate 算左右边界，而 xForDate 里又有 QDate 到天数差的计算。如果每次绘制都算，QDate 虽然不慢，但上万个任务叠加起来也能感觉到。我在模型层给任务条做了一个预计算缓存，把每个任务的 leftX、width、row 一次性算出，绘制时直接读缓存，修改日期时再增量更新，效果很明显。

5.5 常见问题速查表

6. 写在最后：一点个人体会

G06 这套组件真正投入日常使用后，我最大的体会是：甘特图的复杂度不在画图本身，而在数据模型和视图之间的一致性。导航树和甘特图看起来是两个控件，实际上它们只是同一个任务模型的两个投影。把所有状态统一收到模型层，让视图只做“展示和输入”，联动就会顺理成章。如果一开始就想着在视图层互相改来控制对方，后面每加一个功能都要在前面代码上打补丁。

还有一个小技巧分享给正在做类似组件的朋友：调试联动时，不要只看效果，要在模型里临时输出每个展开节点的视觉行号、和对应甘特图绘制行号，打印到一个调试窗口。我踩过最深的坑就是两个行号明明差了 1，视觉上就是看不出来，直到打日志才发现根节点占了一行而甘特图从 0 开始计数时多算了一位。这类“行号偏移量”问题，靠肉眼排查很容易漏，靠日志和边界测试快得多。

G06 目前已经支持多项目切换、任务筛选、里程碑高亮、依赖线拖拽。后续如果想往更深做，可以在甘特图内部增加资源分配泳道、多版本基准线对比，或者把左侧导航树升级成分组多选模式。这些扩展都是基于同一个任务模型来叠加，核心的联动逻辑不用动。希望这篇文章能帮你把自己的甘特图导航组件搭得更顺，少走我走过的弯路。