# useUpload

Used for handling file upload and selection related logic.

## Basic Usage

```ts
import { useUpload } from '@/uni_modules/wot-design-uni'

const { startUpload, abort, chooseFile, UPLOAD_STATUS } = useUpload()

// Choose files
const files = await chooseFile({
  accept: 'image',
  multiple: true,
  maxCount: 9
})

// Start upload
const file = {
  url: 'file://temp/image.png',
  status: UPLOAD_STATUS.PENDING,
  percent: 0
}

startUpload(file, {
  action: 'https://upload-url',
  onSuccess(res) {
    console.log('Upload successful', res)
  },
  onError(err) {
    console.log('Upload failed', err) 
  },
  onProgress(progress) {
    console.log('Upload progress', progress)
  }
})

// Abort upload
abort()
```

## API

### Methods

| Method Name | Description | Parameters | Return Value | Minimum Version |
|-------|------|------|--------|----------|
| startUpload | Start uploading file | file: UploadFileItem, options: UseUploadOptions | UniApp.UploadTask \| void | - |
| abort | Abort upload | task?: UniApp.UploadTask | void | - |
| chooseFile | Choose file | options: ChooseFileOption | Promise<ChooseFile[]> | - |

### UseUploadOptions

| Parameter | Description | Type | Default | Minimum Version |
|-----|------|------|--------|----------|
| action | Upload URL | string | - | - |
| header | Request headers | Record<string, any> | {} | - |
| name | Key corresponding to the file | string | 'file' | - |
| formData | Other form data | Record<string, any> | {} | - |
| fileType | File type | 'image' \| 'video' \| 'audio' | 'image' | - |
| statusCode | Success status code | number | 200 | - |
| uploadMethod | Custom upload method | UploadMethod | - | - |
| onSuccess | Upload success callback | Function | - | - |
| onError | Upload failure callback | Function | - | - |
| onProgress | Upload progress callback | Function | - | - |

### ChooseFileOption

| Parameter | Description | Type | Default | Minimum Version |
|-----|------|------|--------|----------|
| multiple | Whether to support multiple file selection | boolean | false | - |
| sizeType | Size of selected images | Array | ['original', 'compressed'] | - |
| sourceType | Source of file selection | Array | ['album', 'camera'] | - |
| maxCount | Maximum number of selections | number | 9 | - |
| accept | Accepted file types | 'image' \| 'video' \| 'media' \| 'file' \| 'all' | 'image' | - |
| compressed | Whether to compress video | boolean | true | - |
| maxDuration | Maximum video duration (seconds) | number | 60 | - |
| camera | Camera direction | 'back' \| 'front' | 'back' | - |
| extension | Filter by file extension (H5 supports all types, WeChat Mini Program supports filtering when all and file, other platforms do not support) | string[] | - |

## File Selection Quantity Limits

Different platforms have different limits on file selection quantity, which are determined by the uni-app platform APIs themselves:

### WeChat Platform

| Selection Method | Max Count | Description | Use Case |
|-----------------|-----------|-------------|----------|
| `chooseMedia` | 20 | Maximum selection count for images and videos | Used when accept is `image`, `video`, `media` |
| `chooseMessageFile` | 100 | Maximum selection count for files | Used when accept is `file`, `all` |

### H5 Platform

| Selection Method | Max Count | Description | Use Case |
|-----------------|-----------|-------------|----------|
| `chooseImage` | 9 | Maximum selection count for images | Used when accept is `image` |
| `chooseVideo` | 1 | Does not support multiple selection, single file only | Used when accept is `video` |
| `chooseFile` | 100 | Maximum selection count for files | Used when accept is `all` |

::: warning H5 Platform Special Note
The behavior of the count value on the H5 platform is based on the browser's own specifications. Current test results show that it can only limit single/multiple selection, but cannot limit the specific quantity. Moreover, very few mobile browsers actually support multiple selection.
:::

### Other Platforms

| Selection Method | Max Count | Description | Use Case |
|-----------------|-----------|-------------|----------|
| `chooseImage` | 9 | Maximum selection count for images | Used when accept is `image` |
| `chooseVideo` | 1 | Does not support multiple selection, single file only | Used when accept is `video` |

::: tip Tips
- WeChat platform prioritizes `chooseMedia` and `chooseMessageFile`, which have higher selection count limits
- Video selection does not support multiple selection on most platforms
- The actual selectable quantity is further limited by the `maxCount` parameter
:::

## File Selection Quantity Limits

Different platforms have different file selection methods with varying maximum quantity limits, which are determined by the uni-app platform APIs:

### WeChat Platform

WeChat Mini Program platform offers richer file selection capabilities with higher quantity limits:

| Selection Method | Maximum Count | Description | Applicable File Types |
| ---------------- | ------------- | ----------- | -------------------- |
| `chooseMedia` | 20 | Maximum selection count for images and videos | Used when accept is `image`, `video`, or `media` |
| `chooseMessageFile` | 100 | Maximum selection count for files from client sessions | Used when accept is `file` or `all` |

### H5 Platform

H5 platform supports multiple file selection methods:

| Selection Method | Maximum Count | Description | Applicable File Types |
| ---------------- | ------------- | ----------- | -------------------- |
| `chooseImage` | 9 | Maximum selection count for images | Used when accept is `image` |
| `chooseVideo` | 1 | Does not support multiple selection, single video file only | Used when accept is `video` |
| `chooseFile` | 100 | Maximum selection count for files | Used when accept is `all` |

### Other Platforms

Other platforms (such as Alipay Mini Program, DingTalk Mini Program, App, etc.) have relatively limited file selection capabilities:

| Selection Method | Maximum Count | Description | Applicable File Types |
| ---------------- | ------------- | ----------- | -------------------- |
| `chooseImage` | 9 | Maximum selection count for images | Used when accept is `image` |
| `chooseVideo` | 1 | Does not support multiple selection, single video file only | Used when accept is `video` |

::: tip Tips
- When the set `maxCount` exceeds the above platform limits, the actual selection count will be subject to platform limits
- The `chooseFile` function will automatically choose the optimal method based on platform capabilities
- WeChat Mini Program platform prioritizes using `chooseMedia` for selecting images and videos, which has higher selection count limits
- Video selection on non-WeChat platforms is limited by the `chooseVideo` API and only supports single selection
- Platform capability priority: WeChat Platform > H5 Platform > Other Platforms
:::

::: warning maxCount Parameter Limitation
The `maxCount` parameter in `ChooseFileOption` is limited by the underlying platform APIs. Setting a value higher than the platform limit will be automatically capped to the maximum supported value.
:::