# 抽奖大转盘

**Repository Path**: NuggetTeam/lottery-wheel

## Basic Information

- **Project Name**: 抽奖大转盘
- **Description**: No description available
- **Primary Language**: HTML
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-13
- **Last Updated**: 2025-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 班级抽奖大转盘

一个面向初中学生的互动抽奖系统，采用现代化前端技术栈，支持Excel数据导入，实现公平、有趣的随机抽奖功能。

## 🌟 技术亮点

### 前端架构设计
- **模块化设计**：采用清晰的模块化架构，将功能划分为数据管理、UI交互、抽奖逻辑等独立模块
- **状态管理**：实现集中式状态管理模式，统一管理学生、奖品、抽奖历史等数据
- **响应式布局**：基于Flexbox和CSS Grid实现的自适应布局，完美支持桌面和移动设备
- **组件化思维**：将UI元素封装为可复用的组件，提高代码维护性

### 数据处理与存储
- **Excel解析引擎**：集成SheetJS库，支持复杂Excel文件的解析和数据提取
- **智能数据验证**：实现多层数据验证机制，确保导入数据的完整性和准确性
- **双重存储策略**：优先使用IndexDB进行数据持久化，降级方案为localStorage，确保数据不丢失
- **增量数据更新**：支持增量更新学生和奖品数据，避免重复导入

### 可视化与交互
- **动态转盘渲染**：基于ECharts 5.4.3实现的高性能转盘渲染，支持自定义扇形区域和动画效果
- **流畅动画系统**：采用CSS3动画和JavaScript结合的方式，实现转盘旋转、结果展示等流畅动画
- **响应式交互设计**：针对不同设备优化的交互体验，包括触摸、鼠标等多种输入方式
- **视觉反馈系统**：完整的用户操作反馈机制，包括加载状态、错误提示、成功确认等

### 抽奖算法
- **公平随机算法**：基于Fisher-Yates洗牌算法实现的公平随机选择，确保每个学生有相等的机会
- **智能概率管理**：自动管理抽奖池状态，确保在所有学生被抽中前不会重复抽取
- **权重分配系统**：支持奖品权重配置，实现不同中奖概率的奖品分配
- **多轮抽奖支持**：支持多轮抽奖，每轮结束后自动重置抽奖池

### UI/UX设计
- **毛玻璃效果**：采用backdrop-filter实现的现代化毛玻璃效果，增强视觉层次感
- **渐变色彩系统**：精心设计的渐变色彩方案，营造活泼、友好的界面氛围
- **微交互动画**：细致的悬停效果、点击反馈等微交互，提升用户体验
- **语义化HTML结构**：遵循HTML5语义化标准，提高代码可读性和可访问性

## 🎯 功能特性

- **Excel数据导入**：支持从Excel文件导入学生名单和奖品列表，自动识别数据格式
- **可视化抽奖界面**：动态大转盘展示抽奖过程，增强趣味性和参与感
- **智能随机抽取**：确保公平性，所有学生未被选完前不会重复抽取
- **实时数据统计**：实时显示已加载数量、剩余可抽取人数等统计信息
- **抽奖历史记录**：完整记录每轮抽奖结果，支持查看和清空历史
- **数据持久化**：自动保存当前状态，刷新页面后可恢复
- **多页面架构**：分离数据准备和抽奖界面，优化用户体验
- **模板下载**：提供标准Excel模板，简化数据准备流程

## 📱 使用方法

1. **准备数据**：
   - 下载标准Excel模板或按照格式要求准备数据
   - 学生名单包含姓名、班级、院系等信息
   - 奖品列表包含奖品名称、数量、权重等信息

2. **上传数据**：
   - 点击"📋 数据准备"按钮进入数据上传页面
   - 分别上传学生名单和奖品列表Excel文件
   - 系统自动解析并验证数据格式

3. **设置抽奖参数**：
   - 在"抽取学生数量"输入框中设置一次要抽取的学生数量
   - 查看已加载的学生和奖品数量统计

4. **开始抽奖**：
   - 点击"开始抽奖"按钮，大转盘将开始旋转
   - 旋转结束后，系统将显示抽奖结果
   - 查看抽奖历史记录了解历次抽奖情况

5. **管理抽奖池**：
   - 点击"重置抽奖"按钮，可以重新开始抽取所有学生
   - 点击"清空历史记录"按钮，可以清除所有抽奖历史

## 🛠️ 技术实现

### 核心技术栈
- **前端框架**：纯HTML5 + CSS3 + JavaScript (ES6+)
- **可视化库**：ECharts 5.4.3 - 用于转盘渲染和数据可视化
- **数据处理**：SheetJS 0.18.5 - 用于Excel文件解析
- **数据存储**：IndexDB + localStorage 双重存储策略
- **CSS框架**：自定义CSS，采用Flexbox和Grid布局
- **字体系统**：系统字体栈，确保跨平台一致性

### 架构特点
- **模块化设计**：代码按功能模块组织，便于维护和扩展
- **事件驱动**：基于事件驱动的交互模型，响应式UI更新
- **错误处理**：完善的错误捕获和用户友好的错误提示
- **性能优化**：DOM操作优化、事件委托、防抖节流等性能优化措施

### 数据流设计
```
Excel文件 → SheetJS解析 → 数据验证 → 状态管理 → UI更新
    ↓
IndexDB存储 ← 数据持久化 ← 状态变更 ← 用户操作
```

## 📁 项目结构

```
抽奖大转盘/
├── dist/                    # 生产环境文件
│   ├── css/
│   │   └── style.css       # 样式文件
│   ├── js/
│   │   └── app.js          # 主应用逻辑
│   ├── images/             # 图片资源
│   │   ├── 唐僧.png        # 示例图片
│   │   └── 图片1.png       # 背景图片
│   ├── index.html          # 主页面
│   ├── upload.html         # 数据上传页面
│   └── 抽奖配置.xlsx       # 示例配置文件
├── docs/                   # 项目文档
│   └── 抽奖大转盘/         # 项目文档目录
└── README.md               # 本说明文件
```

## ⚠️ 注意事项

1. **Excel文件格式要求**：
   - 第一行应为列标题（建议使用"姓名"、"班级"、"院系"等）
   - 确保数据格式正确，避免空行或无效数据
   - 支持多种Excel格式（.xlsx, .xls）

2. **抽奖规则**：
   - 系统会确保在所有学生都被抽中过一次之前，不会重复抽取同一学生
   - 当所有学生都被抽中后，系统会自动重置抽奖池
   - 可通过"重置抽奖"按钮手动重置抽奖池

3. **数据存储**：
   - 系统会自动保存当前抽奖状态和历史记录
   - 刷新页面后，之前的设置和数据会被自动恢复
   - 清除浏览器缓存可能导致数据丢失

4. **浏览器兼容性**：
   - 推荐使用Chrome、Firefox、Safari等现代浏览器
   - 确保浏览器支持IndexDB或localStorage功能
   - 需要启用JavaScript才能正常运行

## 🔧 开发说明

如果您想对本项目进行修改或扩展，可以：

1. **样式定制**：修改`css/style.css`调整界面样式和主题
2. **功能扩展**：修改`js/app.js`添加新功能或调整现有逻辑
3. **页面调整**：修改`index.html`和`upload.html`调整页面结构
4. **数据模型**：扩展appState对象添加新的数据字段

### 代码规范
- 使用ES6+语法编写JavaScript代码
- 遵循语义化HTML5标准
- CSS采用BEM命名规范
- 注释清晰，便于团队协作

## 🙏 致谢

本项目使用了以下开源资源：
- [SheetJS (xlsx.js)](https://github.com/SheetJS/sheetjs) - Excel文件解析库
- [ECharts](https://echarts.apache.org/) - 数据可视化库
- [MDN Web Docs](https://developer.mozilla.org/) - 技术文档参考

## 📄 许可证

本项目仅供学习和教育用途。