7.1 KiB
7.1 KiB
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
快速开始
# 安装依赖
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
设计特色
- 🎨 严格按照设计图实现 - 像素级还原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 文件：
// 添加新字段
{
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等
开发者说明
本项目采用最简单有效、优雅的方式实现，避免代码冗余，遵循以下原则：
- 组件化设计 - 每个功能模块独立封装
- 配置驱动 - 通过JSON配置实现灵活的表单生成 ⭐
- 类型安全 - 完整的TypeScript类型定义
- 用户体验 - 流畅的交互和反馈
- 代码质量 - 简洁、可维护的代码结构
License
MIT