151 lines
5.2 KiB
Markdown
151 lines
5.2 KiB
Markdown
# PlayBallTogether - 约球应用
|
||
|
||
## 项目简介
|
||
|
||
这是一个基于Taro + React + TypeScript的约球应用，用户可以发布个人约球活动。
|
||
|
||
## 主要功能
|
||
|
||
### 核心功能特性
|
||
|
||
- ✅ **图片上传** - 支持上传多张活动封面图片
|
||
- ✅ **活动信息填写** - 主题、时间、场地、价格等完整信息
|
||
- ✅ **多玩法选择** - 单打、双打、娱乐拉球、到了再说
|
||
- ✅ **人数控制** - 灵活设置最少到最多参与人数
|
||
- ✅ **NTRP水平设置** - 滑动条选择技能水平区间
|
||
- ✅ **性别偏好** - 支持性别限制或不限
|
||
- ✅ **自动候补** - 开启自动候补逻辑
|
||
- ✅ **多场发布** - 支持同时创建多场活动
|
||
|
||
### 技术架构特性 ⭐
|
||
|
||
- ✅ **动态表单配置** - 通过JSON配置动态生成表单
|
||
- ✅ **组件化架构** - 可复用的字段渲染器
|
||
- ✅ **表单验证** - 自动数据验证和错误提示
|
||
- ✅ **API集中管理** - 统一services目录，按页面功能命名
|
||
- ✅ **Token自动管理** - 自动携带token，处理过期刷新
|
||
- ✅ **请求拦截处理** - 统一错误处理和加载状态
|
||
- ✅ **多人协作友好** - 按页面隔离，避免代码冲突
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: Taro 4.1.5
|
||
- **前端**: React 18 + TypeScript
|
||
- **UI库**: NutUI React Taro
|
||
- **样式**: Sass
|
||
- **状态管理**: React Context + useReducer
|
||
- **本地存储**: Taro Storage API
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
# 或
|
||
yarn install
|
||
|
||
# 开发环境启动
|
||
npm run dev:h5 # H5版本
|
||
npm run dev:weapp # 微信小程序
|
||
npm run dev:alipay # 支付宝小程序
|
||
|
||
# 构建生产版本
|
||
npm run build:h5 # H5版本
|
||
npm run build:weapp # 微信小程序
|
||
npm run build:alipay # 支付宝小程序
|
||
```
|
||
|
||
## 页面路由
|
||
|
||
- `/pages/list/index` - 首页
|
||
- `/pages/publish/publish` - 原发布页面
|
||
- `/pages/publishBall/publishBall` - 新的约球发布页面 ⭐
|
||
- `/pages/dynamicFormDemo/dynamicFormDemo` - 动态表单演示页面 ⭐
|
||
|
||
## 项目结构 🏗️
|
||
|
||
本项目采用**按页面分层、组件共享**的架构设计，便于多人协作开发。
|
||
|
||
```
|
||
src/
|
||
├── components/ # 🔥 公共组件（所有页面共享）
|
||
│ └── DynamicForm/ # 动态表单组件 ⭐
|
||
│ ├── DynamicForm.tsx # 动态表单容器
|
||
│ ├── DynamicForm.scss # 动态表单样式
|
||
│ ├── FieldRenderer.tsx # 字段渲染器
|
||
│ ├── FieldRenderer.scss # 字段渲染器样式
|
||
│ └── index.ts # 组件导出
|
||
├── pages/ # 📱 页面目录（按功能模块划分）
|
||
│ ├── index/ # 首页模块
|
||
│ ├── publish/ # 原发布页面
|
||
│ ├── publishBall/ # 约球发布模块 ⭐
|
||
│ │ ├── publishBall.tsx
|
||
│ │ ├── publishBall.scss
|
||
│ │ └── publishBall.config.ts
|
||
│ └── dynamicFormDemo/ # 动态表单演示模块 ⭐
|
||
│ ├── dynamicFormDemo.tsx
|
||
│ ├── dynamicFormDemo.scss
|
||
│ └── dynamicFormDemo.config.ts
|
||
├── services/ # 🌐 API服务（统一管理）
|
||
│ ├── httpService.ts # HTTP基础服务 ⭐
|
||
│ ├── authService.ts # 认证服务 ⭐
|
||
│ ├── commonApi.ts # 通用API服务 ⭐
|
||
│ ├── publishBallApi.ts # 🔥 约球发布API服务
|
||
│ └── demoApi.ts # 🔥 演示页面API服务
|
||
├── utils/ # 🛠️ 工具函数
|
||
│ ├── tokenManager.ts # Token管理 ⭐
|
||
│ └── storage.ts # 本地存储
|
||
├── config/ # ⚙️ 配置文件
|
||
│ ├── formConfig.ts # 表单配置定义 ⭐
|
||
│ └── exampleConfigs.ts # 示例配置 ⭐
|
||
├── store/ # 📦 全局状态管理
|
||
│ ├── matchStore.ts # Zustand状态管理
|
||
│ └── storage.ts # 本地存储工具
|
||
├── app.ts # 应用入口
|
||
├── app.config.ts # 应用配置
|
||
└── app.scss # 全局样式
|
||
```
|
||
|
||
详细架构说明请查看：[ARCHITECTURE.md](./ARCHITECTURE.md)
|
||
|
||
## 设计特色
|
||
|
||
- 🎨 **严格按照设计图实现** - 像素级还原UI设计
|
||
- 📱 **移动端优先** - 针对手机屏幕优化
|
||
- ⚡ **流畅交互** - 高性能的用户体验
|
||
- 💾 **数据持久化** - 自动保存用户输入
|
||
- 🔄 **状态同步** - 全局状态实时更新
|
||
|
||
|
||
### 图片上传
|
||
- 使用Taro.chooseImage API
|
||
- 支持相册和相机选择
|
||
- 最多支持9张图片
|
||
- 实时预览和删除功能
|
||
|
||
### 表单验证
|
||
- 必填字段验证
|
||
- 数字范围验证
|
||
- 自定义验证规则
|
||
- 友好的错误提示
|
||
|
||
### 响应式设计
|
||
- 适配不同屏幕尺寸
|
||
- 灵活的布局系统
|
||
- 优雅的动画过渡
|
||
|
||
## 如何自定义表单配置
|
||
|
||
## 开发者说明
|
||
|
||
本项目采用最简单有效、优雅的方式实现，避免代码冗余，遵循以下原则：
|
||
|
||
1. **组件化设计** - 每个功能模块独立封装
|
||
2. **配置驱动** - 通过JSON配置实现灵活的表单生成 ⭐
|
||
3. **类型安全** - 完整的TypeScript类型定义
|
||
4. **用户体验** - 流畅的交互和反馈
|
||
5. **代码质量** - 简洁、可维护的代码结构
|
||
|
||
## License
|
||
|
||
MIT |