用户进度系统

相关源文件

• public/images/cursors/add.svg
• public/images/cursors/remove.svg
• src/components/BestPracticeHint.astro
• src/components/FrameRenderer/FrameRenderer.astro
• src/components/FrameRenderer/FrameRenderer.css
• src/components/ReactIcons/DropdownIcon.tsx
• src/components/ResourceProgressStats.astro
• src/components/RoadmapHint.astro
• src/components/TeamVersions/TeamVersions.tsx
• src/components/TopicDetail/TopicDetail.tsx
• src/components/TopicDetail/TopicProgressButton.tsx
• src/components/UserProgress/ProgressShareButton.tsx
• src/data/best-practices/aws/aws.json
• src/data/best-practices/code-review/code-review.json
• src/data/best-practices/frontend-performance/frontend-performance.json
• src/icons/progress.svg
• src/lib/resource-progress.ts

用户进度系统使用户能够在 roadmap.sh 上通过路线图和最佳实践追踪他们的学习历程。它允许用户将主题标记为“已完成”、“进行中”、“已跳过”或“待处理”，并在路线图上可视化这些进度，同时在用户登录时将进度数据在本地存储和服务器之间同步。

概述

进度跟踪系统旨在帮助用户跟踪他们在各种学习路线图和最佳实践中的进展。进度在路线图上以不同的样式视觉化表示，用于已完成、进行中或已跳过的项目。

来源: src/lib/resource-progress.ts9-14 src/components/TopicDetail/TopicProgressButton.tsx28-34

关键组件

进度类型和状态

系统跟踪两种主要资源类型的进度

• 路线图
• 最佳实践

对于这些资源中的每个主题，用户可以将其进度标记为以下状态之一

进度状态	视觉指示器	描述
已完成	绿色样式，删除线文本	主题已完成
学习中	黄色样式，下划线文本	正在学习
已跳过	黑色样式，删除线文本	有意跳过
待处理	默认样式	尚未开始
移除	褪色样式（用于团队自定义）	从视图中移除（团队功能）

来源: src/lib/resource-progress.ts8-14 src/components/FrameRenderer/FrameRenderer.css51-103

进度跟踪架构

来源: src/lib/resource-progress.ts51-81 src/components/TopicDetail/TopicProgressButton.tsx121-151

进度数据流

更新进度

当用户将某个主题标记为已完成、进行中或已跳过时

1. TopicProgressButton 组件触发进度更新
2. updateResourceProgress 函数会带主题信息和所需的进度状态被调用
3. 如果用户已登录，进度将发送到服务器 API
4. 进度也存储在本地存储中
5. 路线图上的视觉指示器通过 renderTopicProgress 函数进行更新
6. 进度统计信息通过 refreshProgressCounters 刷新

来源: src/components/TopicDetail/TopicProgressButton.tsx121-151 src/lib/resource-progress.ts51-82

渲染进度

系统使用 CSS 类来在路线图节点上视觉指示进度状态

来源: src/lib/resource-progress.ts302-330 src/lib/resource-progress.ts345-367

实现细节

本地存储结构

进度数据以以下格式的键存储在本地存储中

${resourceType}-${resourceId}-${userId}-progress

存储的值是一个 JSON 对象，包含

来源: src/lib/resource-progress.ts241-264

进度选择器

系统使用各种 DOM 选择器查找路线图中代表主题的元素

• 具有与主题 ID 匹配的数据属性的元素
• 具有特定 CSS 类的元素
• 自定义路线图节点

这些元素根据进度状态进行定位和样式设置。

来源: src/lib/resource-progress.ts266-300 src/lib/resource-progress.ts302-330

进度计数器

系统跟踪并显示进度统计信息

• 主题总数
• 已完成主题数
• 进行中主题数
• 已跳过主题数
• 总体进度百分比

这些计数器显示在用户界面中，并在进度更改时更新。

来源: src/lib/resource-progress.ts383-506 src/components/ResourceProgressStats.astro13-52

用户交互组件

TopicDetail 组件

TopicDetail 组件是一个弹出窗口，点击后显示主题的详细信息。它包括

• 主题内容和相关资源
• 进度跟踪按钮
• 分享进度的选项

来源: src/components/TopicDetail/TopicDetail.tsx37-628

TopicProgressButton 组件

TopicProgressButton 组件提供了用于更改主题进度状态的用户界面

• 显示当前进度状态并带有颜色指示器
• 带有选项的下拉菜单，可标记为“已完成”、“进行中”、“重置”或“跳过”
• 键盘快捷键（D 代表 Done，L 代表 Learning，R 代表 Reset，S 代表 Skip）

来源: src/components/TopicDetail/TopicProgressButton.tsx20-263

进度统计显示

进度统计信息在用户界面中显示，包括

• 完成百分比
• 已完成主题数（总数中）
• 进行中主题数
• 分享进度的选项

来源: src/components/ResourceProgressStats.astro13-52

团队进度功能

系统还支持基于团队的进度跟踪

• 团队成员可以查看共享路线图
• 团队自定义可以把主题标记为“已移除”
• 进度可以在个人和团队层面进行跟踪
• 路线图的团队版本可以被选择和查看

来源: src/components/TeamVersions/TeamVersions.tsx20-230

进度分享

用户可以使用 ProgressShareButton 组件与他人分享他们的进度，该组件

• 生成一个包含用户进度的可分享 URL
• 允许他人查看用户在路线图上的进度
• 在 URL 中包含用户 ID 作为查询参数

来源: src/components/UserProgress/ProgressShareButton.tsx8-76

API 集成

对于已登录用户，进度与服务器同步

1. 进度更新发送到 API 端点 /v1-update-resource-progress
2. 进度通过 /v1-get-user-resource-progress 从 API 获取
3. 当离线或 API 请求失败时，系统会回退到本地存储
4. 进度数据在本地存储中带有时间戳进行缓存，以最大程度减少 API 请求

来源: src/lib/resource-progress.ts57-82 src/lib/resource-progress.ts143-194 src/lib/resource-progress.ts196-239

结论

用户进度系统是 roadmap.sh 的核心功能，帮助用户跟踪他们的学习历程。它结合了客户端存储和服务器同步，提供了直观的用户界面组件用于更新进度，并在路线图和最佳实践上可视化进度。该系统还支持基于团队的进度跟踪和进度分享功能。