shop-wx/doc/wot-design-uni/docs/en-US/component/use-upload.md

# 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 accept is 'all' or 'file'; other platforms do not support) | string[] | - | - |



## 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.
:::