企业官网建设流程全解析

去年给部门自研的项目管理桌面端做迭代，甘特图里的任务一多，定位就成了大问题。演示到一半，被问到“这个子任务在哪个项目里”，我只能在一堆任务条里来回拖滚动条，场面一度很尴尬。后来我们把导航栏单独拎出来做成一个组件，内部代号G06，专门负责项目甘特图导航：把项目、分组、任务按层级收拢在左侧面板，点击任意一项，右侧甘特图自动滚动到对应任务。这篇文章就把G06的完整设计思路、关键代码、状态联动以及踩过的坑一次说清楚，想给Qt项目管理类客户端加导航面板的同学可以直接参考。

1. 为什么需要一块独立的甘特图导航——需求复盘

1.1 早期版本中定位任务的痛苦

最初的项目管理工具和很多同类软件一样，甘特图区域本身就是一棵“任务树 + 时间条”的组合：最左侧是层级任务表格，右侧是横跨日历的时间条。听起来已经能导航了，对吧？实际用起来完全不是这么回事。

我举个例子：一个项目组有5个并行项目，每个项目下有4到5层子任务。某天用户接到一个临时任务“核对供应商报价”，只知道名字，不确定它在哪个项目里。旧版里他只能先打开项目列表，逐个点进项目，再层层展开任务树，在表格搜索框输入关键词撞运气。就算搜到了，甘特图的时间轴可能还停在半年前，视觉上完全找不到那条任务。这样的定位链路至少需要四次点击加一次滚动，中间任何一步断了就得重来。

更讽刺的是，甘特图自带的任务表格为了兼顾时间条宽度，任务名字列做了较强的缩窄处理，长任务名直接被截断成省略号。用户看到“核对供应……”时根本分不清是报价还是合同。导航栏的缺失不是“少了个面板”的问题，而是让整个甘特图模块在高任务密度下失去了“方向感”。

1.2 导航栏组件G06的定位

G06不是要做成第二个任务编辑树，它的定位非常克制：只负责“看”和“去”，不负责“改”和“增”。导航栏里展示项目、任务分组、重点任务三类节点，用户点击任意节点，右侧甘特图就滚动到对应位置，同时高亮该任务所属的时间条区域。

这种“只读快速定位面板”和编辑树有本质区别。编辑树要求数据实时双向同步，用户怎么改，树就怎么变；导航栏则更关心“当前正在处理什么”“接下来要去哪里”，它的交互重点是跳转、切换、标记风险。所以我在设计时给G06定了几条硬规则：

• 不提供新增、删除、重命名功能，把误操作的入口直接堵死；
• 导航项可以根据任务状态着色，但不允许通过导航栏直接改状态；
• 支持跨项目层级折叠，让用户能快速把视角从“整个组织”收敛到“某个项目”；
• 每个导航项存一份“上次访问时间”，方便做最近使用排序。

这套减法让G06在交互复杂度上比完整任务树低了一个量级，团队上手几乎零成本。

1.3 与常规树形控件的边界划分

做这个需求时，团队里有过一次讨论：为什么不直接复用已有的“项目任务树”控件，非要再造一个导航栏？我的理由有三点。

第一，职责不同。任务树是甘特图数据的一部分，它必须跟随时间滚动保持行位置一致，属于“数据视图”；导航栏是独立的操作面板，属于“导航工具”。两者混在一起，滚动条一拖，树和导航栏的状态就互相打架。

第二，颗粒度不同。任务树默认会把所有叶子任务都铺开，几千条数据展开后视觉噪音很大；导航栏默认只展示项目、分组和里程碑节点，普通任务需要用户手动开启“显示全部任务”才会出现。这样默认状态下的信息量是可控的。

第三，上下文不同。任务树只能展示当前项目，跨项目对比要不断切换页面；导航栏可以在一棵树里同时放下多个项目，并给每个项目分组显示当前任务数、逾期数、进行中数。这些聚合信息在任务树里实现起来会很绕。

所以最终的边界是：任务树管编辑，导航栏管跳转，两者通过任务ID关联，但不共享视图状态。

2. 导航栏组件G06的总体信息架构

2.1 两级导航模型

G06的数据结构不复杂，关键是要在“够用”和“不重”之间找平衡。第一版我试图把任务管理的完整层级都塞进导航栏，结果每个项目下挂五层子节点，光展开一个项目就占了一整屏，滚动体验直接崩。后来调整为标准两级：项目节点 + 分组节点。

分组节点的含义是可以配置的，默认情况下它对应甘特图的分组任务；如果项目里没有分组任务，也可以按“里程碑”“风险任务”“本月新增”这种预置规则自动归类。这种设计的好处是，导航栏的层级深度固定为2到3层，QTreeView的展开折叠效率很高，不会有深层节点导致的状态混乱。

每个节点在内存里用一个轻量结构体表示，这是导航栏模型的基础：

struct NavTreeNode { QString id; // 项目ID或任务ID NavNodeType type; // ProjectNode / GroupNode / TaskNode QString title; QDateTime updateTime; TaskStatus status; // NotStarted / InProgress / Completed / Overdue int childTaskCount; // 分组内任务总数 int overdueCount; // 逾期任务数 QVariant extraData; // 预留扩展信息 };

这个结构本身不含子节点指针，子节点关系由模型层管理，方便后续扩展不同的聚合维度。

2.2 数据源对接与排序策略

G06不直接连数据库，而是订阅上层工作区的数据变更事件。项目管理桌面端打开时，工作区会维护一份“项目-任务索引”，G06通过接口拿到这份索引的子集。之所以是子集，是因为导航栏不需要关心每个任务的工时、依赖关系、成本数据，只需要ID、标题、父分组、状态、更新时间这五个字段。

排序策略也很有讲究。默认按项目创建时间倒序排列，分组节点按任务开始日期排序。用户如果开启“最近访问优先”，导航栏会读取每个节点上次被定位的时间戳，把最近点过的节点提到前面。这个功能在项目经理同时跟进多个项目时特别好用，不需要频繁折叠展开。

2.3 视图层的组织方式

视图层用了QTreeView + 自定义QAbstractItemModel的组合。没有用QStandardItemModel，原因很实际：当项目数量到50个、分组到200个、展开后可见节点上千时，QStandardItem要为每个节点创建几个变体对象，内存占用和创建耗时会明显上涨。自定义模型按需返回数据，可以省掉大量临时对象。

树本身隐藏了表头，关闭了垂直滚动条以外的多余装饰。节点左侧不显示复选框，因为导航栏不做批量勾选。缩进只保留一级，项目节点不缩进，分组和任务节点统一缩进一档，避免过深的缩进在窄面板里挤占文本空间。

导航栏顶部还放了一个 QLineEdit 作为即时过滤框，用户输入关键词时，模型配合 QSortFilterProxyModel 实现大小写不敏感的子串过滤。过滤时保留“父节点匹配则子节点全部保留”的规则，避免出现只看得到分组、看不到项目上下文的断片感。

3. 核心数据链路：从导航项点击到甘特图定位

3.1 为什么选QTreeView加自定义模型

这个组合是Qt桌面端做层级导航最稳妥的选择。QTreeView自带了选择模型、键盘导航、展开折叠、焦点管理，这些功能如果自己用QWidget画，至少要多写两千行代码，而且很难做到无障碍键盘支持。自定义模型则让数据与视图解耦，任务状态刷新只需要触发 dataChanged，不需要重建整棵树。

为了快速把导航项映射到甘特图任务，模型里维护了一个QHash<QString, QModelIndex> m_idToIndex哈希表。任务ID到模型索引的映射在模型加载时一次性建立，后续状态更新和定位请求直接查表，平均耗时可以忽略不计。如果每次点击都从根节点递归搜索目标任务，几千个节点时稳定有几十毫秒延迟，用户能感觉到“卡一下”。

3.2 点击信号链路的完整设计

导航项点击后的链路是：QTreeView::clicked 信号发出索引 -> 模型从索引取出任务ID -> 传给甘特图控制器 -> 控制器换算任务的行位置和时间条位置 -> 视口滚动并高亮。

关键代码可以拆成三块。第一块是导航栏侧的信号发射：

void NavPanel::onTreeClicked(const QModelIndex &index) { if (!index.isValid()) return; const QString taskId = m_model->taskIdForIndex(index); if (taskId.isEmpty()) { // 如果是项目节点，则发射一个“展开/聚焦项目”信号 emit projectFocusRequested(m_model->data(index, ProjectIdRole).toString()); return; } emit taskFocusRequested(taskId); }

第二块是甘特图侧接收请求并按ID定位：

void GanttWidget::focusTask(const QString &taskId) { const auto pos = m_taskPosition.value(taskId); if (!pos.isValid()) return; const QModelIndex rowIndex = m_ganttModel->index(pos.row, 0); // 先保证行可见，再让时间轴滚到任务起点 m_tableView->scrollTo(rowIndex, QAbstractItemView::PositionAtCenter); const QPoint scenePoint = m_ganttScene->taskScenePoint(taskId); m_graphicsView->centerOn(scenePoint); // 高亮任务条持续3秒 m_ganttScene->flashTask(taskId, QColor("#ffe58f"), 3000); }

第三块是控制器层的解耦。导航栏不直接持有甘特图指针，而是通过一个 FocusRequestBus 中转。这样做的好处是，将来导航栏不仅要驱动甘特图，还要联动看板视图、资源视图时，只需要在总线里增加路由，不用改导航栏内部逻辑。

3.3 任务状态的着色与指示

导航栏里每个节点右侧有一个状态圆点，和任务状态一一对应：逾期显示红色、进行中显示蓝色、已完成显示灰色、未开始显示绿色。圆点不是额外绘制控件，而是通过模型 data 函数的 DecorationRole 返回一个 QPixmap。这样绘制性能好，也方便后续换主题。

还有一个容易被忽视的细节：任务被定位后，导航栏会把这个节点的字体临时加粗，并在左侧画一条黄色竖线作为“访问痕迹”。这个状态只保存在视图层，不写回模型，避免污染数据层。如果用户切走了，访问痕迹保留30分钟后自动淡出，既不打扰，又能提示最近去过哪。

4. 状态同步与增量更新的工程实现

4.1 甘特图滚动时导航栏的反向联动

正向联动是“点导航栏，甘特图动”，反向联动是“拖甘特图，导航栏跟着动”。反向联动不能做得太灵敏，否则用户拖滚动条时导航栏选中项会疯狂跳动，视觉上非常晕。

我的做法是节流加回读：甘特图垂直滚动条的 valueChanged 信号不会直接驱动导航栏，而是先记录一个“待同步行号”，启动一个单次定时器，100毫秒后检查该行号对应的任务ID。如果当前可见视口顶部的任务ID和导航栏当前选中项一致，就不做任何操作，否则才调用 setCurrentIndex。这样用户快速拖动滚动条时，导航栏最多每秒更新10次，既跟得上又不至于闪成残影。

节流代码大致长这样：

void GanttWidget::handleScroll(int) { if (!m_syncTimer.isActive()) { m_syncTimer.start(100); } } void GanttWidget::syncNavSelection() { const int topRow = m_tableView->rowAt(0); const QString taskId = m_ganttModel->taskIdAtRow(topRow); if (taskId.isEmpty()) return; if (taskId != m_lastSyncedTaskId) { m_lastSyncedTaskId = taskId; emit taskVisibleChanged(taskId); } }

4.2 任务状态变化后的增量刷新

项目管理工具的数据不是静态的，后端会实时推送任务变更，比如任务开始、逾期、完成。如果闻到变更就调用 model->reset()，导航栏在任务达到两三千时会明显卡顿，展开状态也会全部丢失。增量刷新是必须的选择。

流程是这样的：变更推送到达后，先判断该任务是否在导航栏中可见。不可见（比如任务属于一个折叠状态的项目）则只更新对应节点的聚合计数；可见则更新节点文本、状态圆点和父节点的逾期计数。所有刷新都通过模型的 dataChanged 信号完成，Qt 会自动重绘受影响的行，整棵树的其他部分保持原样。

关键点是父节点的计数更新。当子任务逾期时，父节点右下角的“逾期 2/5”要同步变化，否则用户就会看到导航栏状态和甘特图对不上。

4.3 折叠状态与布局持久化

用户每次打开软件，导航栏都恢复默认全展开，这种体验很糟糕。尤其在一个项目下挂了几十个分组时，用户手动折叠了不需要的组，下次打开又全部展开，他会觉得这个组件“没有记忆”。

G06的解决方案是：在模型层维护一个QSet<QString> m_collapsedKeys，key是“项目ID:分组ID”的拼接。每次节点折叠或展开时，通过 QTreeView 的 collapsed 和 expanded 信号反向更新这个集合。退出时把集合写入 QSettings，再次启动时读取集合，并在模型加载完成后统一执行 setCollapsed。

这里有一个注意点：必须在模型数据挂载完成后再调用 setCollapsed，如果顺序反了，QTreeView 会因为找不到索引而丢弃折叠操作。我建议监听树的 modelReset 信号，在模型重置完成的槽函数里统一恢复折叠状态。

5. 外观定制与大节点量下的性能优化

5.1 用QSS把导航栏做得更像现代项目工具

Qt 原生 QTreeView 长得很“开发工具”，如果不调样式直接上生产环境，用户第一印象就扣分。G06 的视觉目标很明确：像现代项目管理工具那种左侧深色面板的质感，当前选中项要有明显的左侧色条，悬停要有微妙的背景变化。

核心 QSS 片段如下：

QTreeView#navTree { background: #2b2f36; border: none; outline: none; color: #e6e8eb; font-size: 13px; } QTreeView#navTree::item { height: 32px; border-radius: 4px; margin: 2px 6px; } QTreeView#navTree::item:hover { background: #3a3f47; } QTreeView#navTree::item:selected { background: #4a5568; border-left: 3px solid #f0a020; }

使用 QSS 时有几个坑要注意。第一，border-radius和margin在部分Qt版本下对::item的支持有瑕疵，如果发现圆角不生效，可以改用 QStyledItemDelegate 在 paint 里画背景。第二，分支三角箭头在不同系统主题下可能显示不一致，最好用图片替换QTreeView::branch的 open/closed 状态。第三，字体问题：样式里不指定字体时，中文环境可能回退到点阵宋体，锯齿明显。推荐在样式开头统一设置font-family: "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;。

5.2 数千任务节点下的渲染策略

G06在开发时被要求能承载“五千个分组节点、两万个任务节点”的数据量。这个量级下，QTreeView 的默认渲染策略扛不住，必须做几个优化。

第一，启用setUniformRowHeights(true)。所有导航项的行高固定为32像素，Qt 可以在滚动时用整行高度快速计算可见范围，避免逐行测量。如果你允许节点换行或者动态高度，这个优化就不能用，所以我从一开始就限定了所有导航项只显示一行文本加一个状态点。

第二，使用懒加载子节点。默认情况下，导航栏模型只加载项目节点和每个项目的前30个分组。用户展开项目节点时再去后端拉取全部分组数据；展开分组时再拉取该分组的任务列表。配合canFetchMore和fetchMore两个虚函数，QTreeView 自己会管理“点击展开才加载”的行为。

第三，尽可能减少样式重绘。状态圆点用装饰角色返回的图片比直接在 delegate 里 drawEllipse 更高效，因为QPixmap有缓存，每次重绘只是贴图。实测优化前后的对比差异非常明显：

第四，过滤时不要即时重建模型。用户输入关键词后，QSortFilterProxyModel 的 setFilterFixedString 是增量过滤的，比手动遍历节点重建树快得多。实测两万节点下过滤延迟在50ms以内。

6. 实际迭代中踩过的坑与最后交付的样子

6.1 滚动双向联动导致的事件风暴

最典型的一个坑，发生在反向联动刚做完时。甘特图滚动会触发导航栏选中项变化，导航栏选中项变化又触发甘特图重新定位，甘特图重新定位又触发滚动信号……最终两个控件像踢皮球一样互相触发，界面进入肉眼可见的闪烁状态，CPU占用直接拉满。

排查过程花了一个下午。最初我以为是信号槽连接重复，把连接检查了两遍，没问题。后来在滚动槽函数里加了几行断点日志，发现一个问题：甘特图 scrollTo 执行完，滚动条没动，但 valueChanged 依然被触发了一遍。原因是我们用了centerOn视图中心定位，它内部会先滚动再微调，产生了两次信号。

最终解决方案是双保险。第一，导航栏选中项变化后再设置甘特图定位前，先判断目标任务ID是否已经在当前视口中心，是就不执行任何滚动操作。第二，在两个方向的联动代码里都加QSignalBlocker，把对方控件的信号封住几百毫秒。这样即使定位代码有细微的额外滚动，也会在一个节流周期内被吞掉。

6.2 中文字体回落与QSS变量不生效

交付测试时发现，在一台纯净环境的Windows机器上，导航栏中文显示成细体宋体，和旁边甘特图区域的字体截然不同。查了半天，根因是QSS里没有显式设置字体族，Qt 在无样式时回退到系统默认字体。而甘特图区域用了自定义 delegate，delegate 内部有一个QFont f明确的字体族，所以看起来不一样。

修复就是在导航栏的QSS里加一行字体声明，同时为了保证跨平台一致，字体列表要同时包含 Windows 的 “Microsoft YaHei” 和 Linux 的 “Noto Sans CJK SC”，按顺序回落。

另外一个和QSS相关的坑：团队里有人想在样式里定义变量方便换主题，写了--nav-bg: #2b2f36;然后用var(--nav-bg)引用。Qt 的 QSS 解析器不支持这个语法，直到 Qt 6.5 才开始支持部分自定义属性。结论是别指望像前端那样在 QSS 里做变量，老老实实用 Qt 的属性系统setProperty加样式状态，或者用QPalette统一管理配色。

6.3 用户反馈与最终效果

G06在内部试用了两周，收集到的反馈集中在三个点。第一，用户希望点击项目节点时，除了折叠展开，最好能双击直接切换到项目总览页，这个功能后来加上了。第二，有用户反馈“显示所有任务”开启后导航栏太长，所以我们在导航栏底部加了一个“只显示我参与的”开关，实现上就是给模型加了一个过滤条件，按负责人字段过滤。第三，用户希望状态圆点旁边能显示数字角标，比如“进行中 5”，帮助快速感知项目进展。

当前版本的导航栏已经稳定跑在内部工具里，打开三个大型项目的导航面板耗时约400毫秒，日常展开折叠操作没有可感知的延迟。组件本身也抽成了独立库，后续准备复用到一个按周迭代的看板视图上。

最后分享一个小技巧：导航栏这类“点击才展开”的树组件，配合键盘上下键移动选中项时，用户往往希望选中项变化后甘特图能实时跟随。这个功能我建议不要做成即时的，而是用300毫秒的悬停延迟，否则用户只是路过某一项，甘特图就跟着跳来跳去，非常恼人。把延迟值做成可调配置，不同习惯的用户体验会好很多。