212 lines
7.1 KiB
Markdown
212 lines
7.1 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/index/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设计
|
||
- 📱 **移动端优先** - 针对手机屏幕优化
|
||
- ⚡ **流畅交互** - 高性能的用户体验
|
||
- 💾 **数据持久化** - 自动保存用户输入
|
||
- 🔄 **状态同步** - 全局状态实时更新
|
||
|
||
## 核心功能实现
|
||
|
||
### 动态表单配置 ⭐
|
||
- **JSON驱动** - 通过配置文件定义表单结构
|
||
- **字段类型丰富** - 支持10+种字段类型（图片上传、文本输入、多选、计数器、滑动条等）
|
||
- **灵活配置** - 支持验证规则、默认值、选项配置
|
||
- **自动渲染** - 根据配置自动生成对应的UI组件
|
||
- **类型安全** - 完整的TypeScript类型定义
|
||
|
||
### 支持的字段类型
|
||
- `image-upload` - 图片上传
|
||
- `text-input` - 文本输入
|
||
- `number-input` - 数字输入
|
||
- `time-display` - 时间显示
|
||
- `venue-input` - 场地输入（带箭头）
|
||
- `multi-select` - 多选按钮
|
||
- `counter` - 计数器（min/max）
|
||
- `slider` - 滑动条
|
||
- `radio-group` - 单选按钮组
|
||
- `checkbox` - 复选框
|
||
|
||
### 图片上传
|
||
- 使用Taro.chooseImage API
|
||
- 支持相册和相机选择
|
||
- 最多支持9张图片
|
||
- 实时预览和删除功能
|
||
|
||
### 表单验证
|
||
- 必填字段验证
|
||
- 数字范围验证
|
||
- 自定义验证规则
|
||
- 友好的错误提示
|
||
|
||
### 响应式设计
|
||
- 适配不同屏幕尺寸
|
||
- 灵活的布局系统
|
||
- 优雅的动画过渡
|
||
|
||
## 如何自定义表单配置
|
||
|
||
### 修改表单字段
|
||
|
||
编辑 `src/config/formConfig.ts` 文件：
|
||
|
||
```typescript
|
||
// 添加新字段
|
||
{
|
||
key: 'newField', // 字段唯一标识
|
||
type: 'text-input', // 字段类型
|
||
title: '新字段', // 显示标题
|
||
required: true, // 是否必填
|
||
placeholder: '请输入内容', // 占位符
|
||
defaultValue: '', // 默认值
|
||
validation: { // 验证规则
|
||
min: 1,
|
||
max: 100,
|
||
message: '请输入1-100字符'
|
||
}
|
||
}
|
||
|
||
// 修改现有字段
|
||
{
|
||
key: 'playStyle',
|
||
type: 'multi-select',
|
||
title: '活动玩法',
|
||
options: [
|
||
{ label: '新玩法', value: 'new-style' }, // 添加新选项
|
||
{ label: '单打', value: '单打' },
|
||
// ... 其他选项
|
||
]
|
||
}
|
||
```
|
||
|
||
### 支持的配置选项
|
||
|
||
- **基础配置**: `key`, `type`, `title`, `required`, `placeholder`, `hint`
|
||
- **默认值**: `defaultValue`
|
||
- **验证规则**: `validation.min`, `validation.max`, `validation.message`
|
||
- **选项配置**: `options` (用于选择类型字段)
|
||
- **特殊配置**: `config.maxImages`, `config.minValue`, `config.showArrow` 等
|
||
|
||
## 开发者说明
|
||
|
||
本项目采用最简单有效、优雅的方式实现，避免代码冗余，遵循以下原则：
|
||
|
||
1. **组件化设计** - 每个功能模块独立封装
|
||
2. **配置驱动** - 通过JSON配置实现灵活的表单生成 ⭐
|
||
3. **类型安全** - 完整的TypeScript类型定义
|
||
4. **用户体验** - 流畅的交互和反馈
|
||
5. **代码质量** - 简洁、可维护的代码结构
|
||
|
||
## License
|
||
|
||
MIT |