mini-programs/docs/PublishBall使用说明.md

发布球局功能使用说明

功能概述

发布球局功能允许用户创建和发布体育活动，包括图片上传、详细信息填写等完整流程。

主要特性

1. 图片上传组件 (UploadImages)

• ✅ 支持最多9张图片上传
• ✅ 6张以内显示网格布局，超过6张自动分页滑动
• ✅ 支持图片预览和删除
• ✅ 拍照或从相册选择
• ✅ 响应式设计，支持暗色模式

2. 动态表单系统 (DynamicForm)

• ✅ 基于配置的动态表单渲染
• ✅ 支持多种字段类型：文本、数字、选择器、日期时间、开关、单选、多选、位置选择
• ✅ 完整的表单验证
• ✅ 实时错误提示
• ✅ 美观的UI设计

3. 位置选择功能

• ✅ 支持地图选择位置
• ✅ 一键获取当前位置
• ✅ 地址显示和验证

4. 草稿保存系统

• ✅ 自动保存草稿（2秒延迟）
• ✅ 页面刷新后自动恢复
• ✅ 草稿过期管理（7天）
• ✅ 提交成功后自动清除

文件结构

src/
├── components/
│   ├── UploadImages/
│   │   ├── index.tsx           # 图片上传组件
│   │   └── index.scss          # 组件样式
│   └── DynamicForm/
│       ├── index.tsx           # 动态表单组件
│       └── index.scss          # 组件样式
├── config/
│   └── formSchema/
│       └── publishBallFormSchema.ts  # 表单配置
├── pages/
│   └── publishBall/
│       ├── index.tsx           # 发布页面
│       ├── index.scss          # 页面样式
│       └── index.config.ts     # 页面配置
└── utils/
    └── locationUtils.ts        # 位置相关工具函数

使用方法

1. 页面导航

// 跳转到发布页面
Taro.navigateTo({
  url: '/publish_pages/publishBall/index'
})

2. 组件使用

UploadImages组件

import UploadImages from '../../components/UploadImages/index'

<UploadImages
  value={images}
  onChange={handleImagesChange}
  maxCount={9}
  className="custom-class"
/>

DynamicForm组件

import DynamicForm from '../../components/DynamicForm/index'
import { publishBallFormSchema } from '../../config/formSchema/publishBallFormSchema'

<DynamicForm
  schema={publishBallFormSchema}
  initialValues={initialValues}
  onValuesChange={handleFormValuesChange}
  onSubmit={handleSubmit}
/>

3. 自定义表单配置

// 在 publishBallFormSchema.ts 中添加新字段
{
  key: 'customField',
  label: '自定义字段',
  type: FieldType.TEXT,
  placeholder: '请输入',
  required: true,
  rules: [
    { required: true, message: '此字段为必填' }
  ]
}

支持的表单字段类型

类型	说明	示例
TEXT	文本输入	活动标题
TEXTAREA	多行文本	活动描述
SELECT	下拉选择	运动类型
DATE	日期选择	活动日期
TIME	时间选择	开始时间
NUMBER	数字输入	人数限制
SWITCH	开关按钮	公开活动
RADIO	单选按钮	技能要求
CHECKBOX	多选框	活动标签
LOCATION	位置选择	活动地点

样式特性

设计系统

• 🎨 统一的色彩方案
• 📱 响应式设计
• 🌙 深色模式支持
• ✨ 流畅的动画效果
• 🔧 可定制的主题

交互体验

• 👆 触感反馈
• 🔄 加载状态
• ⚠️ 错误提示
• 💾 自动保存
• 🎯 焦点管理

开发注意事项

1. 图片上传: 实际项目中需要实现真实的图片上传API
2. 位置服务: 需要配置地图服务的API密钥
3. 表单验证: 可根据业务需求扩展验证规则
4. 草稿存储: 使用本地存储，注意存储容量限制
5. 权限管理: 需要申请相册、相机、位置等权限

扩展性

添加新的字段类型

1. 在 FieldType 枚举中添加新类型
2. 在 DynamicForm 组件的 renderField 方法中添加处理逻辑
3. 在样式文件中添加对应样式

自定义验证规则

// 在表单配置中添加自定义验证
rules: [
  {
    pattern: /^1[3-9]\d{9}$/,
    message: '请输入正确的手机号'
  }
]

主题定制

通过修改 SCSS 变量来定制主题颜色和样式。

性能优化

• 图片懒加载和压缩
• 表单防抖处理
• 组件按需加载
• 样式按需引入

---

此功能已完全按照设计稿实现，包括颜色、间距、样式等所有细节。