# rn- LangApp

**Repository Path**: web_74/rn--lang-app

## Basic Information

- **Project Name**: rn- LangApp
- **Description**: LangApp - 语言学习应用
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-26
- **Last Updated**: 2026-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LangApp - 语言学习应用

一款基于 React Native + Expo 开发的跨平台语言学习应用，支持 iOS、Android 和 Web 端。采用现代化技术栈，提供沉浸式语言学习体验。

## 目录

- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [类型定义](#类型定义)
- [状态管理](#状态管理)
- [快速开始](#快速开始)
- [页面说明](#页面说明)
- [开发指南](#开发指南)
- [开发计划](#开发计划)

## 功能特性

### 🌍 多语言支持
- **支持语言**：英语、西班牙语、日语、法语等
- **语言切换**：随时切换学习目标语言
- **独立进度**：每个语言独立的学习进度追踪
- **母语显示**：显示语言的母语名称和国旗图标

### 📚 课程系统
- **分级设计**：初级、中级、高级三个难度等级
- **结构化单元**：每个课程包含多个学习单元（Lesson）
- **进度追踪**：实时同步课程完成进度
- **课程筛选**：支持按状态筛选（全部/进行中/已完成）

### 📝 练习模块
| 练习类型 | 说明 |
|----------|------|
| 词汇练习 | 单词记忆与识别，支持图片辅助 |
| 语法练习 | 语法规则学习与应用，选择题形式 |
| 听力练习 | 听力理解与训练，音频播放 |
| 口语练习 | 发音练习（待实现） |
| 阅读练习 | 阅读理解训练（待实现） |

### 👤 用户系统
- **账户管理**：用户注册与登录
- **个人资料**：头像、昵称自定义
- **学习偏好**：选择目标学习语言
- **安全退出**：一键退出登录

### 🎮 游戏化元素
- **经验值系统 (XP)**：完成课程获得经验值
- **等级系统**：积累经验值提升等级
- **连续学习 (Streak)**：记录每日学习连续天数
- **成就系统**：解锁各种学习成就徽章

### 📊 统计功能
- **时间维度**：每日/每周/每月学习统计
- **准确率**：练习正确率分析
- **学习天数**：累计活跃天数追踪
- **课程完成**：已完成课程数量统计

### ⚙️ 设置选项
- 通知提醒设置
- 每日学习目标设定
- 深色/浅色模式切换
- 音效开关
- 自动播放音频

## 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| React Native | 0.81.5 | 跨平台移动应用框架 |
| Expo | SDK 54 | 开发工具与运行时环境 |
| React | 19.1.0 | UI 库 |
| TypeScript | ~5.9.2 | 类型安全的 JavaScript |
| Zustand | ^4.5.7 | 轻量级全局状态管理 |
| React Navigation | ^6.x | 页面导航管理 |
| @expo/vector-icons | ^14.0.0 | 图标库（Ionicons） |

### 为什么选择这些技术？

- **Expo SDK 54**：最新稳定版，支持 React 19，提供更好的开发体验
- **Zustand**：比 Redux 更轻量，API 更简洁，TypeScript 支持更好
- **React Navigation 6**：业界标准的 React Native 导航解决方案
- **TypeScript**：提供类型安全，减少运行时错误

## 项目结构

```
lang-app/
├── assets/                     # 静态资源
│   ├── adaptive-icon.png       # Android 自适应图标
│   ├── favicon.png             # Web favicon
│   ├── icon.png                # 应用图标
│   └── splash-icon.png         # 启动画面图标
│
├── src/
│   ├── components/             # 可复用组件
│   │   ├── GrammarExercise.tsx # 语法练习组件
│   │   ├── ListeningExercise.tsx # 听力练习组件
│   │   └── VocabularyExercise.tsx # 词汇练习组件
│   │
│   ├── navigation/             # 导航配置
│   │   └── AppNavigator.tsx    # 根导航器
│   │
│   ├── store/                  # Zustand 状态管理
│   │   ├── userStore.ts        # 用户状态
│   │   ├── languageStore.ts    # 语言状态
│   │   ├── courseStore.ts      # 课程状态
│   │   ├── statsStore.ts       # 统计状态
│   │   ├── gamificationStore.ts # 游戏化状态
│   │   └── index.ts            # 统一导出
│   │
│   ├── screens/                # 页面组件
│   │   ├── Home.tsx            # 首页
│   │   ├── CourseList.tsx      # 课程列表
│   │   ├── Lesson.tsx          # 课程单元
│   │   ├── Exercise.tsx        # 练习页面
│   │   ├── Stats.tsx           # 统计页面
│   │   ├── Profile.tsx         # 个人资料
│   │   ├── Login.tsx           # 登录页面
│   │   ├── Register.tsx        # 注册页面
│   │   ├── LanguageSelect.tsx  # 语言选择
│   │   └── Achievements.tsx    # 成就页面
│   │
│   └── types/                  # TypeScript 类型定义
│       └── index.ts            # 统一类型导出
│
├── App.tsx                     # 应用入口组件
├── app.json                    # Expo 配置文件
├── index.ts                    # 应用启动入口
├── package.json                # 项目依赖配置
├── tsconfig.json               # TypeScript 配置
└── readme.md                   # 项目说明文档
```

## 类型定义

项目使用 TypeScript 进行严格的类型定义：

```typescript
// 语言类型
interface Language {
  id: string;           // 语言唯一标识
  name: string;         // 语言英文名
  nativeName: string;   // 语言母语名
  flag: string;         // 国旗 emoji
  progress: number;     // 学习进度 0-1
}

// 课程类型
interface Course {
  id: string;           // 课程唯一标识
  languageId: string;   // 所属语言 ID
  level: number;        // 难度等级 1-3
  title: string;        // 课程标题
  description: string;  // 课程描述
  isCompleted: boolean; // 是否完成
  progress: number;     // 完成进度 0-100
  lessons: Lesson[];    // 包含的学习单元
}

// 学习单元类型
interface Lesson {
  id: string;
  courseId: string;
  title: string;
  type: 'vocabulary' | 'grammar' | 'listening' | 'speaking' | 'reading';
  isCompleted: boolean;
  exercises: Exercise[];
}

// 练习类型
interface Exercise {
  id: string;
  lessonId: string;
  type: 'vocabulary' | 'grammar' | 'listening';
  question: string;
  options?: string[];
  correctAnswer: string;
  audioUrl?: string;
}

// 用户类型
interface User {
  id: string;
  name: string;
  email: string;
  avatar?: string;
  totalXP: number;          // 总经验值
  level: number;            // 当前等级
  streak: number;           // 连续学习天数
  selectedLanguage: string; // 当前学习语言
  learningLanguages: string[];
  lastActivity?: Date;
}

// 成就类型
interface Achievement {
  id: string;
  title: string;
  description: string;
  icon: string;           // Ionicons 图标名
  isUnlocked: boolean;
  unlockedAt?: Date;
  requirement: {
    type: 'xp' | 'streak' | 'lessons' | 'accuracy';
    value: number;
  };
}

// 统计类型
interface Stats {
  dailyXP: number;            // 今日获得 XP
  weeklyXP: number;           // 本周获得 XP
  monthlyXP: number;          // 本月获得 XP
  totalDaysActive: number;    // 总活跃天数
  totalLessonsCompleted: number; // 完成课程数
  totalLearningTime: number;  // 总学习时间（分钟）
  accuracy: number;           // 总体正确率
  maxStreak: number;          // 最长连续天数
}
```

## 状态管理

项目使用 Zustand 进行状态管理，每个 Store 职责单一：

### userStore - 用户状态
```typescript
// 状态
currentUser: User | null;
isLoading: boolean;
error: string | null;

// 操作
setUserLoading: () => void;
setUserSuccess: (user: User) => void;
setUserError: (error: string) => void;
logoutUser: () => void;
updateUserProfile: (profile: Partial<User>) => void;
```

### languageStore - 语言状态
```typescript
// 状态
availableLanguages: Language[];
currentLanguage: Language | null;

// 操作
selectLanguage: (languageId: string) => void;
updateLanguageProgress: (languageId: string, progress: number) => void;
```

### courseStore - 课程状态
```typescript
// 状态
courses: Course[];
selectedCourse: Course | null;

// 操作
selectCourse: (courseId: string) => void;
updateCourseProgress: (courseId: string, progress: number) => void;
completeLesson: (lessonId: string) => void;
```

### statsStore - 统计状态
```typescript
// 状态
userStats: Stats;

// 操作
updateDailyXP: (xp: number) => void;
updateAccuracy: (isCorrect: boolean) => void;
incrementLessonsCompleted: () => void;
```

### gamificationStore - 游戏化状态
```typescript
// 状态
level: number;
xp: number;
streakDays: number;
achievements: Achievement[];

// 操作
addXP: (amount: number) => void;
updateStreak: () => void;
unlockAchievement: (achievementId: string) => void;
```

## 快速开始

### 环境要求
- Node.js >= 18.0.0
- npm >= 9.0.0 或 yarn >= 1.22.0
- Expo CLI（可选，npx 可直接运行）

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd lang-app
```

2. **安装依赖**
```bash
npm install
# 或使用 yarn
yarn install
```

3. **启动开发服务器**
```bash
npm start
# 或
npx expo start
```

4. **运行应用**

| 平台 | 命令 | 说明 |
|------|------|------|
| iOS | `npm run ios` | 需要 Xcode 和 iOS 模拟器 |
| Android | `npm run android` | 需要 Android Studio 和模拟器 |
| Web | `npm run web` | 在浏览器中运行 |

5. **使用 Expo Go 扫码运行**
   - 在手机上安装 Expo Go 应用
   - 扫描终端显示的二维码

## 页面说明

### 首页 (Home)
- 显示用户信息和等级
- 今日学习目标进度
- 当前学习语言切换
- 继续学习快捷入口
- 快捷功能入口

### 课程列表 (CourseList)
- 按难度分级展示课程
- 支持筛选（全部/进行中/已完成）
- 显示课程进度
- 点击进入课程详情

### 课程单元 (Lesson)
- 显示单元内容概览
- 开始练习按钮
- 单元完成状态

### 练习页面 (Exercise)
- 词汇/语法/听力练习
- 实时反馈正确/错误
- 完成后获得 XP 奖励

### 统计页面 (Stats)
- 学习数据可视化
- 每日/每周/每月统计
- 准确率分析

### 个人资料 (Profile)
- 用户信息展示
- 学习数据汇总
- 设置选项
- 退出登录

### 成就页面 (Achievements)
- 成就列表展示
- 解锁状态
- 成就详情

### 登录/注册 (Login/Register)
- 邮箱密码登录
- 新用户注册
- 社交账号登录（待实现）

### 语言选择 (LanguageSelect)
- 可用语言列表
- 学习进度显示
- 切换学习语言

## 开发指南

### 添加新页面

1. 在 `src/screens/` 创建新组件
2. 在 `src/navigation/AppNavigator.tsx` 添加路由
3. 更新类型定义 `RootStackParamList`

### 添加新 Store

1. 在 `src/store/` 创建新文件
2. 定义状态接口和初始状态
3. 在 `src/store/index.ts` 导出

### 代码规范

- 使用 TypeScript 严格模式
- 组件使用函数式组件 + Hooks
- 样式使用 StyleSheet.create
- 遵循 ESLint 规则

### 提交规范

```
feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建/工具相关
```

## 开发计划

### 已完成 ✅
- [x] 项目基础架构搭建
- [x] TypeScript 类型定义
- [x] Zustand 状态管理
- [x] 首页与语言选择
- [x] 课程列表与课程详情
- [x] 练习模块（词汇、语法、听力）
- [x] 用户系统（登录、注册、个人资料）
- [x] 游戏化元素（XP、等级、Streak）
- [x] 成就系统
- [x] 统计功能
- [x] 页面布局优化
- [x] 导航系统完善

### 进行中 🚧
- [ ] 后端 API 集成
- [ ] 数据持久化（AsyncStorage）

### 计划中 📋
- [ ] 社交功能（好友、排行榜）
- [ ] 语音识别练习
- [ ] 离线模式支持
- [ ] 推送通知
- [ ] 深色模式完善
- [ ] 多语言国际化

## 屏幕预览

| 首页 | 课程列表 | 练习界面 |
|:----:|:--------:|:--------:|
| 用户信息与学习进度 | 分级课程展示 | 互动式练习 |

| 个人资料 | 成就系统 | 统计页面 |
|:--------:|:--------:|:--------:|
| 设置与学习数据 | 解锁成就展示 | 学习数据分析 |

## 常见问题

### Q: 启动时报依赖版本警告？
A: 运行 `npx expo install --fix` 自动修复依赖版本。

### Q: Android 模拟器无法连接？
A: 确保 Android Studio 模拟器正在运行，或尝试 `adb reverse tcp:8081 tcp:8081`。

### Q: iOS 模拟器报错？
A: 确保已安装 Xcode 和 Command Line Tools，运行 `sudo xcode-select --switch /Applications/Xcode.app`。

## 贡献指南

1. Fork 本项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交修改 (`git commit -m 'feat: add some amazing feature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 联系方式

如有问题或建议，欢迎提交 Issue 或联系开发者。

---

Made with ❤️ and React Native