企业官网建设流程全解析

做教育类桌面客户端的时候，课程导航一直是个绕不开的活儿。用户要在一个窗口里看到章、节、课时的层级关系，要清楚自己学到哪了，还得能一键跳回上次退出的位置。市面上的现成组件大多只解决“展示目录”这一层，进度状态、学习记忆、快速定位这些交互上的细节，往往要自己重写一遍。我这次分享的G03组件，就是专门为这类场景设计的课程进度导航栏，核心解决三件事：进度可视化的清晰度、层级目录的浏览效率、以及课程学习位置的记忆恢复。如果你正在用Qt做在线教育、企业内部培训系统或者任何带“学习路径”概念的桌面应用，这套设计和实现思路可以直接参考。

先说清楚G03是什么定位。我把它定义成一个“组件”而不是一个“控件”，因为只有控件还不够，课程导航牵扯到数据模型、状态管理、界面刷新、交互响应四条线，必须把它们封装成一套完整的东西，才能在不同项目之间复用。G03的输入是一个课程结构的数据源，输出是一个带进度状态、支持折叠展开、可响应点击跳转的侧边导航栏。它不关心课程内容长什么样，也不关心播放器怎么实现，只负责“导航”这件事。

下面我会从需求分析、模型设计、界面实现、踩坑记录、扩展思路五个部分展开，尽量把每一步为什么要这么做讲透，而不是只给一堆代码片段。

1. 课程导航为什么值得做成独立组件：需求与痛点拆解

很多项目一开始觉得“不就是左边放个列表吗”，结果做着做着就跑偏了。我拆过好几个类似的客户端，归纳下来，课程导航真正复杂的地方在三个层面。

第一个层面是课程本身的多级结构。一门课通常有章，章下面有节，节下面可能还有课时，有些培训类课程甚至会有“模块—单元—知识点”这种更深的层级。直接用一个树控件当然可以，但树控件默认的交互样式和视觉语言非常有限，下拉箭头的反馈感也很弱，放进教育场景里显得很“工具”，不“学习”。而课程导航不仅是目录，它要暗示用户“你的学习进度在哪里”，这种暗示靠普通的树节点是表达不出来的。

第二个层面是学习进度的状态模型。一个节点至少有四种状态：未开始、学习中、已完成、锁定。很多课程还会要求先修完上一节才能解锁下一节，这时候节点还要承担“解锁/锁定”的状态展示。更麻烦的是，状态不是静态的，用户看完一个视频、做完一次测验，状态就变了，导航栏需要立刻反映这种变化。如果状态逻辑散落在业务代码里，今天这里改一下，明天那里改一下，很快就会失控。所以状态必须建模，必须和界面分离。

第三个层面是使用场景的特殊性。桌面客户端不像手机App，窗口可以拉大拉小，导航栏要适应不同的宽度；用户可能一边看视频一边点目录找其他小节，导航栏的每个操作都要有即时反馈；还有用户关掉程序再打开，应该自动定位到上次学习的位置，学习位置本身也要持久化。这些都是隐藏需求，不拆解清楚，做出来的东西就只是个静态列表。

G03的定位就是把这几个问题一次性收口。它提供一个统一的进度数据接口，外部只要把课程章节结构和每个节点的进度状态喂进来，它负责渲染、交互和状态变更后的自刷新。业务侧不需要关心导航栏内部是怎么画的，只需要监听它发出的跳转信号。这样不管是换课程类型还是换皮肤，导航栏都不用大改。

2. G03的数据模型设计：先把“课程结构”和“学习进度”彻底分开

写界面之前，我花在数据模型上的时间比写界面多得多。因为根据我以往的经验，凡是后期改起来想骂人的项目，基本都是前期数据结构没设计好。

2.1 课程节点的统一抽象

G03没有把“章”“节”“课时”硬编码成三个不同的类，而是用一个统一的节点结构来描述。因为从导航的角度看，章、节、课时只是层级不同，它们需要暴露给导航栏的属性是高度一致的：节点ID、父节点ID、标题、类型、排序号、进度状态、是否解锁、附加信息。统一抽象的好处是，渲染代码和交互代码只需要处理一套逻辑，不会出现“章节要单独写一套、课时又写一套”这种重复劳动。

在定义节点状态时，我建议在枚举里把“锁定”和“未开始”分开。很多同学喜欢用布尔值控制可点击性，但真实业务里，锁定是课程规则的强制要求，未开始只是用户的主动选择，两者在交互反馈上完全不同。锁定节点点击时要么无响应要么弹提示，未开始节点点击后应该正常跳转，只是它没有进度而已。G03的枚举是四态：Locked、NotStarted、InProgress、Completed，这样视觉和交互都有明确的处理依据。

2.2 进度状态的存储与恢复

导航栏不负责持久化进度，它只从外部读取。外部拿到进度数据后，通常以JSON或数据库记录的方式保存。G03内部维护一棵渲染树，树的每个节点都保存着当前的进度状态和最近一次的访问时间戳。组件暴露一个setProgress(nodeId, state)方法，业务侧在用户看完某一节后调用，组件自动更新对应的节点绘制状态；暴露一个restore(nodeId)方法，用于恢复上次的学习位置。

这里有个设计细节值得单独说：为什么节点要有访问时间戳？因为“恢复上次学习位置”这个需求，靠的不总是“哪个节点已完成”，而是“用户最后一次点了哪个节点”。用户可能看完第三章后跳回第一章复习，这时候最近访问位置应该是第一章，而不是第三章。所以G03内部会记录每个节点的lastVisited字段，组件发出currentChanged信号时，业务侧只需要把这个节点ID存下来，下次启动传回restore()，组件就会自动展开对应章节并滚动到可视区域。

2.3 折叠展开状态的维护

折叠展开看起来只是一个UI细节，但落到数据里还是挺有讲究的。G03用每个节点的expanded布尔值来记录章节的展开状态，并且把这份状态也交给外部保存（或者存到配置文件里）。这样用户展开或收起了哪些章，下次打开程序还能保持原样。如果不做这一步，每次启动导航栏都是全展开或全收起的状态，用户定位起来就会很累。

数据模型设计完成后，整个组件的接口也顺理成章地稳定下来：

G03NavigationBar ├─ setCourseTree(rootNode) ├─ setProgress(nodeId, state) ├─ restore(nodeId) ├─ setExpanded(nodeId, expanded) ├─ signal currentChanged(nodeId) └─ signal nodeClicked(nodeId, state)

外部业务只需要操作这套接口，完全不需要碰内部的绘制和布局代码。

3. 界面渲染与交互实现：从绘制一个进度节点说起

模型定了，剩下的就是界面。G03是纯自绘组件，没有用现成的QTreeView，原因后面会细说。先看最核心的绘制单元：一个“带进度状态的课程节点”是怎么画出来的。

3.1 节点绘制的三层结构

每个节点在导航栏里呈现为一行，高度固定（通常48像素），分为左、中、右三个区域。左侧是进度指示器，中间是标题和类型描述，右侧是折叠箭头或附加信息。进度指示器我采用的是“圆形序号+状态颜色”的方案：未开始节点是深灰色空心圆，学习中节点是蓝色实心圆且带一个半圆弧进度条，已完成节点是绿色实心圆加对勾，锁定节点则是变淡的圆和一把小锁。这个视觉方案在用户测试中反馈最好，比纯文字强很多，因为状态扫一眼就能确认。

绘制代码放在paintEvent()里，逐行绘制可见节点。绘制时优先处理鼠标悬停、选中、以及状态指示器的不同分支，用QPainter画圆、画弧、画对勾。核心绘制函数大致长这样：

void G03NodeWidget::paintNode(QPainter* painter, const G03NodeData& node, const QRect& rect, int depth) { QRect iconRect = QRect(rect.left() + 8 + depth * 16, rect.center().y() - 10, 20, 20); painter->setRenderHint(QPainter::Antialiasing, true); switch (node.state) { case Completed: paintCompletedIcon(painter, iconRect); // 绿色实心圆 + 白色对勾 break; case InProgress: paintInProgressIcon(painter, iconRect, node.progressAngle); break; case NotStarted: paintNotStartedIcon(painter, iconRect); break; case Locked: paintLockedIcon(painter, iconRect); break; } // 画标题文字 painter->drawText(QRect(rect.left() + 40 + depth * 16, rect.top(), rect.width() - 60, rect.height()), Qt::AlignVCenter | Qt::AlignLeft, QFontMetrics(painter->font()).elidedText(node.title, Qt::ElideRight, textWidth)); }

这里有一个容易被忽略的点：所有绘制必须控制在可见范围内。课程目录可能有几千个节点，如果全都交给paintEvent去画，滚动起来会明显卡顿。G03的处理方式是只实例化可视区域的节点item，不可见的不画，这个策略后面会专门讲。

3.2 为什么不用QTreeView，而是自己绘制

很多人会问，QTreeView配合自定义Delegate不是也能实现吗？对，能用，但我在权衡后还是选择了自绘。主要原因是QTreeView的模型/视图体系太重，为了一个纯展示的导航栏引入QAbstractItemModel、QStyledItemDelegate这一套，以及缩进、展开箭头、选择态这些内置行为，反而增加了定制成本。自绘组件在控制视觉细节、实现流畅动画、减少依赖这几方面有明显优势，维护起来也比较容易。

当然，自绘的前提是需求相对稳定。如果产品要求极其复杂的树形交互（比如拖拽、多选、临时编辑节点），那还是认认真真用QTreeView更合适。G03锁定的是“导航”这个场景，交互边界清晰，自绘是性价比最高的方案。

3.3 折叠展开与缩进对齐

章节的展开收起用节点前面的箭头图标控制，同时整行也响应双击展开。缩进按照节点深度计算，一级章缩进16像素，二级节缩进32像素，三级课时缩进48像素。为了视觉整齐，图标、标题、缩进这三者的距离在绘制时统一取值，不会被字体大小或系统DPI影响。高DPI屏幕上，绘制坐标要用设备无关像素，字体用pt而不是px设定，否则在缩放比例下会出现文字模糊或错位。

交互上有一个经验值：可点击区域一定要大于视觉区域。很多用户点目录时手不会特别准，如果箭头只有十几个像素宽，点击命中率会很糟糕。G03把折叠箭头的实际热区扩大到整行左侧40像素范围，点击箭头区域触发展开收起，点击其他区域正常跳转。这个小改动对体感提升很大。

4. 记忆恢复、状态联动与信号穿透：导航栏的“大脑”封装

纯UI绘制只是肉，导航栏真正值钱的地方在于它跟业务的联动逻辑。G03把这一部分集中在了G03Controller这个内部类里，导航栏对外只暴露功能接口，交互细节不外泄。

4.1 当前项的定位与高亮

G03每次收到restore(nodeId)或者用户点击某个节点后，内部会维护一个currentNodeId。当前项的高亮样式是细色的左边条加浅色背景，绘制时区别于悬停效果。这里的关键是定位要处理“展开路径”：如果目标节点所在章节是收起状态，需要先把它所有祖先节点置为展开，再滚动到可见区域。

滚动定位用ensureWidgetVisible()不太好使，因为这是个自绘组件，不是QScrollArea的子控件。G03的做法是自己维护一个滚动偏移量，在wheelEvent和拖拽滚动条时更新。计算出目标节点的y坐标后，判断是否需要调整偏移量以让节点居中或进入可视区域。定位过程耗时极短，但注意不要在定位过程中频繁重绘整棵树，G03的做法是只触发一次update()。

4.2 进度更新后的界面自刷新

G03有一个很实用的能力：外部调一次setProgress(nodeId, state)，内部会自动重绘该节点，同时刷新它所有祖先节点的汇总状态。比如一个章下面有5个课时，4个已完成时，章的进度指示器会显示“80%完成”的效果，这个效果是通过父节点子节点的状态统计出来的。

汇总状态的实时计算逻辑：

G03ProgressState G03Controller::summarizeState(const G03NodeData& node) const { int total = 0, completed = 0, inProgress = 0; collectChildStates(node, total, completed, inProgress); if (total > 0 && completed == total) return G03ProgressState::Completed; if (inProgress > 0 || completed > 0) return G03ProgressState::InProgress; return G03ProgressState::NotStarted; }

这种“叶子状态向上汇总”的设计，让用户对整章的完成情况一目了然，也避免了外部业务重复计算汇总数据。

4.3 点击穿透与信号约束

导航栏最终要跟播放器或内容区通信，G03用一个信号统一对外传达意图：currentChanged(QString nodeId)。但这个信号在两种情况下会变得很吵：一是初始化恢复位置时，二是在加载大批量数据时。G03因此在Controller里加了一个“信号闸门”，语义上类似静默切换模式。批量设置状态时关闭信号，等初始化完成后再打开，避免业务侧收到一堆无效信号导致多次加载内容。

另外，锁定的节点在点击时不发跳转信号，而是发一个lockedNodeClicked(QString nodeId)信号，让业务侧决定是弹提示还是打开购买引导。这个细节能让产品做很多运营向的处理，G03保持中立，不替业务做决定。

5. 踩坑记录：从“能用”到“好用”之间的五个坎

这部分是我最想写的，因为很多问题不在官方文档里，是跑到线上、跑完真实课程数据后才暴露的。G03前后迭代了三轮，下面这几个坑最有代表性。

5.1 第一次用QListWidget做载体，节点一多就卡

最早的原型贪图省事，用QListWidget加setItemWidget往每个条目塞自定义的QWidget。课程少的时候没问题，一旦课程章节超过500个节点，滚动时FPS直接掉到十几。排查后发现瓶颈不在绘制，而在setItemWidget创建的数百个QWidget实例，每个都带着事件过滤、样式表、布局开销，滚动时全部参与计算。这也是我后来决心改成纯自绘的一个直接原因。结论：界面元素多且有大量自定义绘制时，QWidget并不是越多越好，能合并到一个paintEvent里的尽量合并。

5.2 高DPI缩放导致文字错位

第二版在2K屏（缩放150%）上出现文字和图标错位，排查到根因是绘制时代码里混合使用了devicePixelRatio相关的缩放和普通像素坐标。Qt在高DPI下会自动缩放窗口，但如果自绘代码里再手动乘一次缩放系数，相当于做了双重缩放。修复方法是统一走QPainter的坐标变换，代码里一律用逻辑像素，让Qt自己处理物理像素映射。画出来的图标和文字从此再没有模糊和错位问题。

5.3 缩略标题的格式刷新不及时

节点标题很长时，绘制代码用QFontMetrics::elidedText()截断成省略号。问题出在字体变化和宽度变化时，省略文本没有及时重算，导致某些节点显示成残缺字符串。最后的处理办法是，在resizeEvent和字体变更事件中触发布局失效，强制下一帧重绘所有可见节点。代码里还加了一个cachedElidedTextMap，同一节点同一宽度下不重复计算截断文本，几千节点的刷新时间从几十毫秒降到了几毫秒。

5.4 展开收起时的“闪烁感”

初次实现展开收起时直接把整棵树的布局重建了一遍，导致收起再展开后所有行都重新创建，滚动位置和视觉状态都丢了，用户看到的是明显的闪烁。后来改成“保留节点实例，只更新可见性和偏移量”的策略，展开和收起变成一次纯绘制的更新，视觉上就非常顺滑了。这里的关键是：收起一个章节时不应该销毁下面的子节点实例，而是把它们标记为不可见并跳过绘制，这样重新展开时的状态才能原样恢复。

5.5 锁定与解锁之间的歧义

早期版本里，锁定的节点在视觉上只是颜色变淡，很多用户反馈“看着像还没加载出来的灰色”，完全没意识到是锁。后来调整视觉：锁定节点除了变淡，还在右侧加了一个小锁图标，鼠标悬停时也会变成禁用的手型光标。一个状态如果视觉上不够明显，本质上等于没有这个状态，所以后来每次增加状态，我都会先做一轮用户可辨识度测试再定稿。

6. 性能优化与后续扩展：面向几千节点的真实场景

G03不只是支持一两百个节点的课程，我拿它跑过一个4000多节点的大型培训课程数据，滚动和展开依然能保持满帧，靠的是下面这几层优化。

6.1 可见区间的精确计算

导航栏的高度是固定的，假设每行48像素，可视区域能显示大约25行。G03根据当前的滚动偏移量算出firstVisibleIndex和lastVisibleIndex，绘制时只对这25行左右的节点调用paintNode。哪怕树里有4000个节点，单帧需要绘制的也只有几十个，这就是性能的关键。这里要说一下具体做法：节点在内部被拍平存储成一个按顺序排列的列表，折叠章节的子节点会在拍平计算时被跳过，所以展开状态下几千行、收起状态下几百行，绘制数量只跟当前可见行数有关。

拍平列表的维护逻辑大致是：

void G03Controller::rebuildFlatList() { m_flatList.clear(); appendNodeRecursively(m_rootNode, 0); } void G03Controller::appendNodeRecursively(const G03NodeData& node, int depth) { m_flatList.append({&node, depth, m_flatList.size()}); if (node.expanded) { for (const auto& child : node.children) { appendNodeRecursively(child, depth + 1); } } }

点击折叠箭头或双击展开箭头时，只需要调用一次rebuildFlatList()再刷新可见区域，整个组件就完成了结构更新。这个拍平列表的构建在面对几千节点时也不过是毫秒级操作，对性能没有任何压力。

6.2 节点状态更新的增量重绘

如果一次进度刷新只影响一个节点，全量重绘整个导航栏是浪费。G03把可见的节点行拆成了独立的矩形区域，setProgress时只更新该节点所在的那一块矩形。但要注意，如果节点处在折叠状态（不可见），直接刷新矩形会失败，所以内部会先检查该节点是否在平铺列表中，如果不在就只更新数据、不触发绘图。这个分支处理听起来很基础，但很多第一版实现就是没注意，导致“更新完进度后界面半天不动”的诡异问题。

6.3 样式主题与深色模式适配

G03支持两套内置主题（浅色/深色），配色全用QPalette的role取色，而不是写死十六进制颜色值。原因是桌面环境可能自动切换深浅色模式，写死颜色在系统切换后会出现刺眼的色块。组件的边框、背景、文字、高亮四类颜色分别对应四个固定的palette role，在主题切换时只需要调用一次reloadTheme()，所有可见节点自动重绘成新配色。

6.4 和播放器联动的扩展建议

G03目前不直接负责播放器联动，但我在预留后续扩展时加了两个可选的钩子：一个是playbackProgress(nodeId, percent)接口，用于课程视频播放时实时更新“学习中”节点上的半弧进度条；另一个是setFocusMode(bool enabled)，开启后自动隐藏已完成节点，让用户专注在当前未完成的内容上。这两个功能对培训类应用很有价值，架构上也只是在现有模型上增加两个字段，不会破坏原有的数据结构。

如果下一步要做移动端适配，G03的绘制层可以平移，只需要替换输入事件处理和滚动方式；如果要做Web版，核心的进度状态模型和汇总算法可以直接映射到前端逻辑里复用。组件的好处就在这里：业务逻辑和界面渲染分离后，换平台不至于伤筋动骨。

7. 集成G03时的接入步骤与建议

最后把G03接到真实项目里的步骤梳理一遍，方便直接实操。

第一步是把组件源码加入项目，G03不依赖任何第三方库，纯Qt Widgets模块就能编译，Qt 5.12以上版本都可以用。第二步是构造课程树数据，把数据库或JSON里的章节结构转换成G03的节点结构，注意标注好每个节点的parentId和sortOrder。第三步是调用setCourseTree(rootNode)把数据灌进去，组件会自己构建拍平列表并初始渲染。第四步是连接currentChanged信号，在槽函数里加载对应的课程内容或跳转到对应页面。第五步是保存进度，每次用户学完某个节点时调用setProgress(nodeId, state)，退出前把currentNodeId存进配置文件，启动时再调restore(nodeId)。

这个流程跑通以后，导航栏的日常维护就非常轻了。业务侧完全不需要知道组件内部怎么绘制、怎么优化，只需要关注课程数据的准确性和进度更新的时机。如果想调整导航栏的外观，只需要修改主题配色和节点绘制函数；如果产品提出新的交互需求，比如拖拽调整章节顺序、批量标记完成状态，也只需要在现有Controller里增加接口。

课程进度导航这种组件，看起来见仁见智，但真正做成一个可靠、可复用、高帧率的东西，还是要沉淀一些细节的。G03从原型到现在的版本，最大的体会就是：先把数据模型和交互边界定义清楚，再去写绘制代码，往往会少走很多弯路。如果你正在做类似的需要体现学习路径的桌面端产品，这套思路可以直接套用，组件层面的代码也欢迎按实际场景改造。