school-miniprogram/src/components/uploadFile/README.md

# Upload 上传组件 API 文档

## 组件路径

`@/components/uploadFile/index`

## 说明

上传接口地址固定为 `app.globalData.upFileUrl`，组件内部自动附加 `loginState`，无需外部传入。

组件仅提供上传按钮，不维护文件列表状态，不显示文件列表，不包含文件预览功能。父页面需要自行处理文件列表的显示和管理。

组件通过事件通知父页面文件选择、上传进度、上传成功、上传失败等状态，父页面需要监听这些事件并更新自己的文件列表。

## Properties 入参

| 参数 | 说明 | 类型 | 默认值 | 必填 |
| --- | --- | --- | --- | --- |
| `maxCount` | 最大上传文件数 | `Number` | `9` | 否 |
| `maxSize` | 单文件最大限制（byte） | `Number` | `10485760`（10MB） | 否 |
| `accept` | 允许的文件类型数组，可选值：`'image'` \| `'video'` \| `'file'` | `Array` | `['image']` | 否 |
| `extensions` | 自定义文件后缀（仅 accept 含 `'file'` 时生效），如 `['.pdf', '.doc']` | `Array` | `[]` | 否 |
| `readonly` | 只读模式（不显示上传按钮） | `Boolean` | `false` | 否 |
| `useSlot` | 是否使用自定义上传区域插槽 | `Boolean` | `false` | 否 |
| `fileList` | 已有文件列表（用于判断是否还能上传） | `Array` | `[]` | 否 |

### fileList 数据结构

```ts
{
  uid: string       // 文件唯一标识
  url: string       // 文件路径
  type: string      // 文件类型: 'image' | 'video' | 'file'
  name: string      // 文件名
  size: number      // 文件大小(byte)
}
```

## Events 事件

| 事件名 | 说明 | 回调参数 |
| --- | --- | --- |
| `bind:success` | 单文件上传完成 | `{ file: UploadFile, response: any }` |
| `bind:error` | 上传失败 | `{ file: UploadFile, error: Error }` |

### 事件返回的 UploadFile 结构

```ts
{
  uid: string                              // 文件唯一标识
  url: string                              // 文件路径（上传成功后为远程 url）
  type: 'image' | 'video' | 'file'         // 文件类型
  name: string                             // 文件名
  size: number                             // 文件大小(byte)
  status: 'pending' | 'uploading' | 'success' | 'error'  // 上传状态
  progress: number                         // 上传进度 0-100
}
```

## Slots 插槽

| 插槽名 | 说明 |
| --- | --- |
| `upload-area` | 自定义上传区域布局，需同时设置 `useSlot="{{true}}"`。使用时上传触发器尺寸自适应 slot 内容 |

## CSS 变量

| 变量名 | 说明 | 默认值 |
| --- | --- | --- |
| `--upload-bg` | 上传区域背景色 | `#f7f8fa` |
| `--upload-border` | 边框颜色 | `#e5e7eb` |
| `--upload-text-secondary` | 次要文字颜色 | `#9ca3af` |
| `--upload-radius` | 圆角大小 | `16rpx` |
| `--upload-size` | 上传按钮尺寸（仅默认上传框生效，slot 模式自适应） | `160rpx` |

## 使用案例

### 案例 1：使用默认上传框

```json
// page.json
{
  "usingComponents": {
    "upload-file": "@/components/uploadFile/index"
  }
}
```

```xml
<!-- page.wxml -->
<upload-file
  maxCount="{{3}}"
  maxSize="{{5242880}}"
  accept="{{['image']}}"
  fileList="{{fileList}}"
  bind:success="onUploadSuccess"
  bind:error="onUploadError"
/>
```

```ts
// page.ts
Page({
  data: {
    fileList: [] as UploadFile[],
  },

  onUploadSuccess(e: WechatMiniprogram.CustomEvent) {
    console.log('上传成功', e.detail.file, e.detail.response)
    // 添加上传成功的文件到列表
    this.setData({
      fileList: [...this.data.fileList, e.detail.file],
    })
  },

  onUploadError(e: WechatMiniprogram.CustomEvent) {
    console.log('上传失败', e.detail.file, e.detail.error)
    wx.showToast({ title: '文件上传失败', icon: 'none' })
  },
})
```

### 案例 2：使用 slot 自定义上传区域

```xml
<!-- page.wxml -->
<upload-file
  useSlot="{{true}}"
  maxCount="{{5}}"
  accept="{{['image', 'video']}}"
  fileList="{{fileList}}"
  bind:success="onUploadSuccess"
>
  <view slot="upload-area" class="custom-upload-area">
    <image src="/images/upload-icon.png" mode="aspectFit" />
    <text>点击上传</text>
  </view>
</upload-file>
```

```scss
// page.scss
.custom-upload-area {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 12rpx;

  image {
    width: 64rpx;
    height: 64rpx;
  }

  text {
    font-size: 24rpx;
    color: #9ca3af;
  }
}
```