useKnowledgeGraphProgress
约 797 字大约 3 分钟
2025-08-29
简介
用于知识图谱学习进度的可视化与统计的组合式函数。提供颜色与标签映射、节点尺寸随进度自适应、对整图批量应用进度增强、基于前置依赖的学习路径推荐,以及整体进度统计汇总。
接口定义
从 @/types/knowledge-graph 导入(以源码为准):
GraphNode:图节点,包含id、size?、color?、progress?等GraphLink:图连线,source/target可为string | { id: string },含relation_typeGraphData:{ nodes: GraphNode[]; links: GraphLink[] }ProgressStatus:'not_started' | 'in_progress' | 'completed'NodeProgress:{ status: ProgressStatus; progress_score: number }
API 详解
getProgressColor(status, score = 0): string
- 功能:按
ProgressStatus与分数区间返回节点展示色。 - 颜色映射(十六进制):
not_started:灰色#9ca3afin_progress:<30:#fbbf24<70:#f59e0b>=70:#d97706
completed:>=90:#10b981>=70:#059669<70:#047857
getProgressLabel(status, score = 0): string
- 功能:产出进度标签文案。
- 示例:
not_started→未学习in_progress→学习中 ${score}%completed:按分数分别为已完成 ${score}% (优秀|良好|及格)
calculateProgressNodeSize(progress, baseSize = 16): number
- 功能:依据节点进度调整节点尺寸。
- 规则:
not_started:baseSize * 0.8in_progress:baseSize * (0.9 + (progress_score / 100) * 0.3)(范围约0.9x ~ 1.2x)completed:baseSize * 1.3
applyProgressToGraph(graphData, progressMap): GraphData
- 功能:将
progressMap: Map<string, NodeProgress>应用于整图:- 为匹配的节点写入
node.progress - 基于进度重算
node.color与node.size
- 为匹配的节点写入
- 返回:新的
GraphData(不修改入参对象)。
getLearningPath(currentNode, allNodes, allLinks): GraphNode[]
- 功能:在当前节点已完成的前提下,基于连线的
relation_type === 'prerequisite',推荐其后续待学节点。 - 筛选条件:
source为currentNode.id- 目标节点存在且
node.progress?.status === 'not_started'
- 返回:按筛选得到的后续节点列表;若当前节点未完成或无进度,则返回空数组。
calculateProgressStats(nodes): { total, not_started, in_progress, completed, completion_rate, average_score }
- 功能:对节点集合进行进度统计与评分均值计算。
- 统计口径:
- 无
progress视为not_started completion_rate = completed / total * 100average_score仅统计progress_score > 0的节点均值
- 无
使用示例(片段)
const progress = useKnowledgeGraphProgress()
// 1) 颜色与标签
const color = progress.getProgressColor('in_progress', 42)
const label = progress.getProgressLabel('completed', 88) // 已完成 88% (良好)
// 2) 节点尺寸
const size = progress.calculateProgressNodeSize(
{ status: 'in_progress', progress_score: 60 },
18
)
// 3) 应用到整图
const map = new Map<string, NodeProgress>([
['node-1', { status: 'completed', progress_score: 95 }],
['node-2', { status: 'in_progress', progress_score: 40 }],
])
const enhanced = progress.applyProgressToGraph(graphData, map)
// 4) 学习路径推荐(仅在当前节点完成后生效)
const next = progress.getLearningPath(
currentNode,
enhanced.nodes,
enhanced.links
)
// 5) 统计
const stats = progress.calculateProgressStats(enhanced.nodes)
// { total, not_started, in_progress, completed, completion_rate, average_score }技术特点
- 纯计算与幂等:所有方法均为纯函数风格输入/输出,便于测试与复用。
- 视觉语义统一:颜色与尺寸策略对齐进度语义,增强信息密度。
- 非破坏性增强:
applyProgressToGraph返回新对象,不改写原图数据。 - 类型明确:充分利用
ProgressStatus、NodeProgress约束,减少歧义。
使用建议
- 分数与状态一致性:
completed场景建议搭配progress_score >= 70以上的配色梯度以保持视觉期望。 - 默认尺寸:若你的图渲染器有全局尺寸策略,可将
baseSize通过配置传入以保持一致。 - 路径语义:
getLearningPath依赖relation_type='prerequisite'与source → target的方向语义,请确保数据正确建模。 - 缺省进度:后端/同步尚未返回时,可默认构建空
Map与占位progress,避免闪烁。
版权所有
版权归属:Evoliant
许可证:MIT