# 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-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LangApp - 语言学习应用

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

## 目录

- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [快速开始（小白教程）](#快速开始小白教程)
- [使用教程](#使用教程)
- [页面说明](#页面说明)
- [常见问题排错（FAQ）](#常见问题排错faq)
- [开发指南](#开发指南)
- [开发计划](#开发计划)

## 功能特性

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

### 课程系统
- 初级、中级、高级三个难度等级
- 每个课程包含多个学习单元
- 实时同步课程完成进度
- 支持按状态筛选（全部 / 进行中 / 已完成）

### 练习模块
| 练习类型 | 说明 |
|----------|------|
| 词汇练习 | 单词记忆与识别 |
| 语法练习 | 语法规则学习与应用 |
| 听力练习 | 听力理解与训练 |

### 游戏化元素
- 经验值系统（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 | 页面导航管理 |

## 项目结构

```
lang-app/
├── assets/                     # 静态资源（图标、启动画面）
├── src/
│   ├── components/             # 可复用练习组件
│   │   ├── GrammarExercise.tsx
│   │   ├── ListeningExercise.tsx
│   │   └── VocabularyExercise.tsx
│   ├── config/                 # 配置与启动校验
│   │   ├── appConfig.ts        # 应用配置定义
│   │   └── configValidator.ts  # 配置合法性校验
│   ├── constants/              # 全局常量（颜色、尺寸、等级规则）
│   │   └── index.ts
│   ├── navigation/             # 导航配置
│   │   └── AppNavigator.tsx
│   ├── screens/                # 页面组件
│   │   ├── Home.tsx            # 首页
│   │   ├── CourseList.tsx      # 课程列表
│   │   ├── Lesson.tsx          # 课程单元
│   │   ├── Exercise.tsx        # 练习页面
│   │   ├── Stats.tsx           # 统计页面
│   │   ├── Profile.tsx         # 个人资料
│   │   ├── Login.tsx           # 登录页面
│   │   ├── Register.tsx        # 注册页面
│   │   ├── LanguageSelect.tsx  # 语言选择
│   │   └── Achievements.tsx    # 成就页面
│   ├── store/                  # Zustand 状态管理
│   │   ├── userStore.ts
│   │   ├── languageStore.ts
│   │   ├── courseStore.ts
│   │   ├── statsStore.ts
│   │   ├── gamificationStore.ts
│   │   └── index.ts
│   ├── types/                  # TypeScript 类型定义
│   │   └── index.ts
│   └── utils/                  # 通用工具函数
│       ├── helpers.ts          # 数值钳制、邮箱校验等
│       └── uiHelpers.ts        # 友好提示文案
├── App.tsx                     # 应用入口（含配置校验）
├── app.json                    # Expo 配置文件
├── package.json                # 项目依赖配置
└── tsconfig.json               # TypeScript 配置
```

## 快速开始（小白教程）

### 第一步：安装必备工具

1. **安装 Node.js**（版本 18 或更高）
   - 访问 [Node.js 官网](https://nodejs.org) 下载 LTS 版本
   - 安装后打开终端，输入 `node -v` 确认安装成功

2. **安装 Expo CLI**（可选）
   - 在终端执行：`npm install -g expo-cli`

### 第二步：获取项目代码

```bash
git clone <repository-url>
cd lang-app
```

### 第三步：安装依赖

```bash
npm install
```

> 如果安装很慢，可以切换国内镜像：`npm config set registry https://registry.npmmirror.com`

### 第四步：启动开发服务器

```bash
npm start
```

启动后会显示一个二维码和菜单。

### 第五步：在手机上运行

| 方式 | 操作 |
|------|------|
| **手机运行** | 安装 Expo Go App，扫描终端二维码 |
| **Android 模拟器** | 在终端按 `a` 键 |
| **iOS 模拟器** | 在终端按 `i` 键（需要 Mac + Xcode） |
| **浏览器预览** | 在终端按 `w` 键 |

## 使用教程

### 1. 注册和登录
- 首次打开会看到登录页面
- 点击"立即注册"创建新账户
- 填写姓名、邮箱、密码（至少 6 位）即可注册

### 2. 选择学习语言
- 登录后在首页点击语言选择器
- 选择想学的语言（如西班牙语、日语等）

### 3. 开始学习
- 在首页点击"继续学习"卡片
- 或点击底部"课程"标签浏览所有课程
- 选择课程后进入课时列表

### 4. 做练习
- 点击课时中的练习题目
- 选择答案后点击"提交答案"
- 答对获得 10 XP 经验值
- 完成所有练习后自动返回课时

### 5. 查看统计和成就
- 点击底部"统计"标签查看学习数据
- 在首页或统计页点击"成就"查看徽章

## 页面说明

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

### 课程列表
按难度分级展示课程，支持筛选（全部 / 进行中 / 已完成），显示课程进度。

### 练习页面
词汇 / 语法 / 听力练习，实时反馈对错，答对获得 XP 奖励。

### 统计页面
学习数据可视化，包括等级进度、连胜天数、学习时长、本周学习图表和技能分布。

### 成就页面
成就列表展示，支持按全部 / 已解锁 / 未解锁筛选，显示解锁进度。

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

## 常见问题排错（FAQ）

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

### Q: 启动时报 "无法连接到开发服务器"？
**A:** 
1. 确认手机和电脑在同一个 WiFi 网络下
2. 尝试切换网络（某些公共 WiFi 会限制设备间通信）
3. Android 可尝试 `adb reverse tcp:8081 tcp:8081`

### Q: Android 模拟器无法启动？
**A:** 
1. 确认已安装 Android Studio
2. 在 Android Studio 中创建并启动一个虚拟设备（AVD）
3. 在终端按 `a` 键启动 Android

### Q: iOS 模拟器报错？
**A:** 
1. 确认使用 Mac 电脑
2. 安装 Xcode（从 App Store 下载）
3. 运行 `sudo xcode-select --switch /Applications/Xcode.app`

### Q: npm install 安装失败？
**A:** 
1. 尝试删除 `node_modules` 文件夹和 `package-lock.json` 后重新安装
2. 切换国内镜像源：`npm config set registry https://registry.npmmirror.com`
3. 使用 yarn 替代：`yarn install`

### Q: TypeScript 类型检查报错？
**A:** 运行 `npm run typecheck` 查看详细错误，根据提示修正。

### Q: 页面白屏或闪退？
**A:** 
1. 检查终端是否有红色错误信息
2. 尝试按 `r` 键强制刷新
3. 清除缓存重启：`npx expo start --clear`

## 开发指南

### 添加新页面

1. 在 `src/screens/` 创建新组件文件
2. 在 `src/navigation/AppNavigator.tsx` 的 `RootStackParamList` 添加路由类型
3. 添加对应的 `RootStack.Screen`

### 添加新 Store

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

### 添加新工具函数

1. 在 `src/utils/helpers.ts`（纯逻辑）或 `src/utils/uiHelpers.ts`（UI 相关）添加
2. 确保函数有完整注释和类型签名

### 代码规范

- 使用 TypeScript 严格模式（`strict: true`）
- 组件使用函数式组件 + Hooks
- 样式使用 `StyleSheet.create`
- 颜色、尺寸等常量统一放在 `src/constants/index.ts`
- 通用工具函数放在 `src/utils/`
- 禁止使用 `any` 类型（特殊情况需注释说明）

### 提交规范

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

## 开发计划

### 已完成
- [x] 项目基础架构搭建
- [x] TypeScript 类型定义
- [x] Zustand 状态管理
- [x] 首页与语言选择
- [x] 课程列表与课程详情
- [x] 练习模块（词汇、语法、听力）
- [x] 用户系统（登录、注册、个人资料）
- [x] 游戏化元素（XP、等级、Streak）
- [x] 成就系统
- [x] 统计功能
- [x] 启动配置校验
- [x] 通用工具函数封装
- [x] 全局常量管理

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

## 许可证

MIT License

---

Made with React Native + Expo