progress.ts - 儿童模式进度管理

progress.ts - 儿童模式进度管理

概述

管理儿童学习模式的用户进度，使用 localStorage 本地存储学习数据。

数据模型

LevelProgress

interface LevelProgress {
  completed: boolean;      // 是否完成
  stars: number;          // 获得星星数 (0-3)
  completedAt?: string;   // 完成时间 ISO 字符串
}

KidsProgress

interface KidsProgress {
  levels: Record<string, LevelProgress>;  // 各关卡进度
  currentLevel?: string;                   // 当前关卡 slug
  totalStars: number;                      // 总星星数
}

存储键

键用途
kids-progress存储关卡进度和星星数
kids-component-state存储关卡内组件状态
kids-section-completion存储章节完成状态

核心函数

进度管理

getProgress

export function getProgress(): KidsProgress

从 localStorage 获取用户进度。

saveProgress

export function saveProgress(progress: KidsProgress): void

保存用户进度到 localStorage。

completeLevel

export function completeLevel(slug: string, stars: number): KidsProgress

标记关卡为完成状态。

  • 只在新星星数更高时更新
  • 自动设置下一关为当前关卡
  • 更新总星星数

参数:

  • slug: 关卡标识符
  • stars: 获得的星星数 (0-3)

查询函数

isLevelUnlocked

export function isLevelUnlocked(slug: string): boolean

检查关卡是否已解锁。

  • 第一关始终解锁
  • 其他关卡需要前一关完成

getLevelProgress

export function getLevelProgress(slug: string): LevelProgress | undefined

获取指定关卡的进度信息。

getCompletedLevelsCount

export function getCompletedLevelsCount(): number

获取已完成关卡数量。

getTotalStars

export function getTotalStars(): number

获取获得的总星星数。

重置功能

resetProgress

export function resetProgress(): void

清除所有进度数据（保留组件状态）。

clearAllProgress

export function clearAllProgress(): void

清除所有进度数据，包括组件状态和章节完成状态。

组件状态管理

用于保存关卡内交互组件的状态。

getComponentState

export function getComponentState<T>(levelSlug: string, componentId: string): T | null

获取组件状态。

saveComponentState

export function saveComponentState<T>(levelSlug: string, componentId: string, data: T): void

保存组件状态。

clearComponentState

export function clearComponentState(levelSlug: string): void

清除指定关卡的所有组件状态。

章节完成跟踪

isSectionCompleted

export function isSectionCompleted(levelSlug: string, sectionIndex: number): boolean

检查章节的某个部分是否已完成。

markSectionCompleted

export function markSectionCompleted(levelSlug: string, sectionIndex: number): void

标记章节部分为已完成。

clearSectionCompletion

export function clearSectionCompletion(levelSlug: string): void

清除指定关卡的章节完成状态。

hasCompletedInteraction

export function hasCompletedInteraction(levelSlug: string, componentIdPrefix?: string): boolean

检查关卡中是否有任何交互组件已完成。

使用示例

"use client";
import { 
  completeLevel, 
  isLevelUnlocked,
  getTotalStars,
  saveComponentState,
  getComponentState 
} from '@/lib/kids/progress';

// 完成关卡并获得星星
const progress = completeLevel('1-1-meet-promi', 3);

// 检查关卡是否解锁
const canPlay = isLevelUnlocked('1-2-first-words');

// 获取总星星
const stars = getTotalStars();

// 保存组件状态
saveComponentState('1-1-meet-promi', 'quiz-1', { answer: 'A', completed: true });

// 读取组件状态
const state = getComponentState('1-1-meet-promi', 'quiz-1');

安全说明

  • 所有函数都检查 typeof window 以确保在浏览器环境执行
  • 使用 try-catch 处理 localStorage 异常
  • SSR 安全，在服务端返回默认值
← 返回目录