wot-design-uni useUpload 组合式 API 实战指南:文件选择、上传与中断控制
wot-design-uni useUpload 组合式 API 实战指南:文件选择、上传与中断控制
导读
useUpload 是 wot-design-uni 组件库提供的一个组合式 API(Composable Hook),用于在非组件场景下独立处理"文件选择—上传—进度回调—中断控制"的完整链路。它封装了 uni-app 各平台的 chooseImage、chooseMedia、chooseMessageFile、chooseFile、chooseVideo 以及 uni.uploadFile 等原生能力,并在此基础上补齐了统一的状态机、进度回显、状态码判定与自定义上传方法等能力。读完本文,你将掌握 chooseFile 选文件的平台差异、startUpload 上传与回调机制、abort 中断策略,以及 UPLOAD_STATUS 状态机的底层实现,可直接用于业务代码或二次封装。
useUpload 是什么
useUpload 定义于 useUpload.ts,并从 composables/index.ts 统一导出。它对外暴露四个能力:
| 能力 | 说明 |
|---|---|
startUpload(file, options) |
开始上传单个文件,返回 UniApp.UploadTask | void | Promise<void> |
abort(task?) |
中断上传;不传 task 时中断当前任务 |
chooseFile(options) |
选择文件,返回 Promise<ChooseFile[]> |
UPLOAD_STATUS |
上传状态常量对象 |
从源码结构看,useUpload 是 wd-upload 组件内部上传逻辑的抽取与复用(wd-upload.vue 中即通过 const { startUpload, abort, chooseFile, UPLOAD_STATUS } = useUpload() 消费同一份实现),因此你可以把它当作"不带 UI 的上传组件"来使用,在自定义上传交互时尤其顺手。
基础用法
导入
import { useUpload } from '@/uni_modules/wot-design-uni'
const { startUpload, abort, chooseFile, UPLOAD_STATUS } = useUpload()
注意:useUpload() 是一个实例化调用,每次调用都会创建独立的内部状态(如当前上传任务 currentTask),多个页面或组件各自调用互不干扰。
选择文件
// 选择文件
const files = await chooseFile({
accept: 'image',
multiple: true,
maxCount: 9
})
chooseFile 返回 Promise<ChooseFile<a href="https://link.gitcode.com/i/963a098f579bb0d7b28a527ed233e2b1" target="_blank">]>,每个 ChooseFile 包含 path(临时地址)、size(大小)、name(文件名,仅 H5)、type(image/video/file)、duration(时长)、thumb(缩略图)等字段(见 [types.ts)。
开始上传
// 开始上传
const file = {
url: 'file://temp/image.png',
status: UPLOAD_STATUS.PENDING,
percent: 0
}
startUpload(file, {
action: 'https://upload-url',
onSuccess(res) {
console.log('上传成功', res)
},
onError(err) {
console.log('上传失败', err)
},
onProgress(progress) {
console.log('上传进度', progress)
}
})
中断上传
// 中断上传
abort()
abort 有两种调用方式:传入 UniApp.UploadTask 时只中断该任务;不传参数时中断 useUpload 内部记录的上一个 currentTask。源码中该逻辑位于 useUpload.ts。
API 详解
方法
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| startUpload | 开始上传文件 | file: UploadFileItem, options: UseUploadOptions | UniApp.UploadTask | void | Promise |
| abort | 中断上传 | task?: UniApp.UploadTask | void |
| chooseFile | 选择文件 | options: ChooseFileOption | Promise<ChooseFile[]> |
UseUploadOptions
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| action | 上传地址 | string | - |
| header | 请求头 | Record<string, any> | {} |
| name | 文件对应的 key | string | 'file' |
| formData | 其它表单数据 | Record<string, any> | {} |
| fileType | 文件类型 | 'image' | 'video' | 'audio' | 'image' |
| statusCode | 成功状态码 | number | 200 |
| uploadMethod | 自定义上传方法 | UploadMethod | - |
| onSuccess | 上传成功回调 | Function | - |
| onError | 上传失败回调 | Function | - |
| onProgress | 上传进度回调 | Function | - |
源码中 UseUploadOptions 还额外定义了文档表之外的三个可选字段(见 useUpload.ts),值得在实际开发中利用:
statusKey(默认'status'):文件对象中状态字段的 key。startUpload会以file[statusKey] = UPLOAD_STATUS.LOADING标记上传中,成功/失败后同步改写为SUCCESS/FAIL。如果你的文件对象状态字段不叫status,可通过它指定。abortPrevious(默认false):是否在开启新任务前自动中断上一次上传任务,常用于"同一时间只允许一个文件在传"的场景。extension(string<a href="https://link.gitcode.com/i/5ba7b3f3e01fbd0bc11146aae299d32b" target="_blank">]):按扩展名过滤文件(如['.jpg']),H5 支持全部类型过滤,微信小程序仅在accept为all/file时支持,其余平台不支持(详见 [types.ts)。
ChooseFileOption
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| multiple | 是否支持多选文件 | boolean | false |
| sizeType | 所选的图片的尺寸 | Array | ['original', 'compressed'] |
| sourceType | 选择文件的来源 | Array | ['album', 'camera'] |
| maxCount | 最大可选数量 | number | 9 |
| accept | 接受的文件类型 | 'image' | 'video' | 'media' | 'file' | 'all' | 'image' |
| compressed | 是否压缩视频 | boolean | true |
| maxDuration | 视频最大时长(秒) | number | 60 |
| camera | 摄像头朝向 | 'back' | 'front' | 'back' |
| extension | 根据文件拓展名过滤(H5支持全部类型过滤,微信小程序支持all和file时过滤,其余平台不支持) | string[] | - |
补充两点源码确认的语义:
accept的可选值中,'media'表示同时支持图片和视频、'file'表示图片视频之外的所有文件类型、'all'表示全部类型;其中'media'与'file'仅微信支持,'all'仅微信与 H5 支持(见 types.ts)。compressed、maxDuration、camera仅在与视频相关的accept(video / media)下生效,camera可选'back'/'front'(见 types.ts)。
状态机:UPLOAD_STATUS
UPLOAD_STATUS 在 useUpload.ts 中定义,对应 UploadStatusType 的四种取值:
| 常量 | 值 | 含义 |
|---|---|---|
| UPLOAD_STATUS.PENDING | 'pending' | 待上传(初始态) |
| UPLOAD_STATUS.LOADING | 'loading' | 上传中 |
| UPLOAD_STATUS.SUCCESS | 'success' | 上传成功 |
| UPLOAD_STATUS.FAIL | 'fail' | 上传失败 |
其流转逻辑在 startUpload 内部闭环完成:
- 调用
startUpload时立即将file[statusKey]置为LOADING; onSuccess分支将状态改写为SUCCESS并清空currentTask;onError分支将状态改写为FAIL,同时写入file.error = error.errMsg并清空currentTask;onProgress分支将file.percent = res.progress实时回写进度。
也就是说,业务侧只需维护文件对象的 status / percent 字段,上传期间的状态与进度会自动被 hook 更新,非常适合配合列表渲染展示"上传中/成功/失败"的 UI 状态。
startUpload 的底层实现
startUpload 的关键在于"默认上传方法与自定义上传方法的分流"。其逻辑位于 useUpload.ts:
- 若传入
uploadMethod(函数),则调用uploadMethod(file, formData, uploadOptions),完全交由业务方实现上传逻辑; - 否则走默认的
defaultUpload,内部调用uni.uploadFile。
defaultUpload 的调用链(useUpload.ts)值得关注:
const uploadTask = uni.uploadFile({
url: options.action,
header: options.header,
name: options.name,
fileName: options.name,
fileType: options.fileType,
formData,
filePath: file.url,
success(res) {
if (res.statusCode === options.statusCode) {
options.onSuccess(res, file, formData) // 状态码匹配 → 成功
} else {
options.onError({ ...res, errMsg: res.errMsg || '' }, file, formData) // 否则视为失败
}
},
fail(err) {
options.onError(err, file, formData)
}
})
currentTask = uploadTask
uploadTask.onProgressUpdate((res) => {
options.onProgress(res, file)
})
return uploadTask
要点:
- 成功判定:以
res.statusCode === options.statusCode(默认 200)为准,HTTP 层面请求成功但业务状态码不符时会被归入onError。 - 进度监听:通过
uploadTask.onProgressUpdate订阅,将原生进度透传给onProgress(res, file)。 - 任务句柄:返回
uploadTask并缓存到currentTask,因此abort()(不传参)能中断"最近一次上传",调用方也可自行持有返回的 task 精细化控制。 - 自定义方法签名:
UploadMethod的入参为(uploadFile, formData, options),其中options包含action、header、name、fileName、fileType、statusCode、abortPrevious及成功/失败/进度三个回调,允许返回UniApp.UploadTask | void | Promise<void>(见 types.ts)。
chooseFile 的平台分支实现
chooseFile 是文档中"文件选择数量限制"一节的实现来源,其核心是一个按 accept 分派的 Promise 封装(useUpload.ts),并配合 #ifdef MP-WEIXIN 等条件编译进行平台分流:
| accept | 微信小程序 | 其他平台(含 H5) |
|---|---|---|
| image | uni.chooseMedia({ mediaType: ['image'] }) |
uni.chooseImage(H5 额外传 extension) |
| video | uni.chooseMedia({ mediaType: ['video'] }) |
uni.chooseVideo(H5 额外传 extension) |
| media | uni.chooseMedia(图片+视频) |
该值仅微信支持,其他平台走默认分支 |
| file | uni.chooseMessageFile |
仅微信支持 |
| all | H5 走 uni.chooseFile;微信走 uni.chooseMessageFile |
- |
| 其他/默认 | uni.chooseMedia |
uni.chooseImage |
选择结果会经过 formatImage、formatVideo、formatMedia 三个格式化函数统一为 ChooseFile<a href="https://link.gitcode.com/i/e97b5e76102c52cb5bcb4c7d18e44703" target="_blank">] 结构(见 [useUpload.ts),其中:
- 图片格式化为
path / name / size / type: 'image' / thumb; - 视频额外携带
thumbTempFilePath作为缩略图、duration作为时长; - 微信
chooseMedia返回的媒体项按item.fileType区分图片/视频并分别映射缩略图; - 钉钉小程序(MP-DINGTALK)下图片文件在
files字段中,代码已做兼容处理(useUpload.ts)。
文件选择数量限制
不同平台对文件选择数量有不同的限制,这些限制由 uni-app 平台 API 本身决定,useUpload 只能将 maxCount 透传给底层 API,无法突破平台上限。
微信平台
| 选择方法 | 最大数量 | 说明 | 适用场景 |
|---|---|---|---|
chooseMedia |
20 | 选择图片和视频时的最大数量限制 | accept 为 image、video、media 时使用 |
chooseMessageFile |
100 | 选择文件时的最大数量限制 | accept 为 file、all 时使用 |
H5平台
| 选择方法 | 最大数量 | 说明 | 适用场景 |
|---|---|---|---|
chooseImage |
9 | 选择图片时的最大数量限制 | accept 为 image 时使用 |
chooseVideo |
1 | 不支持多选,只能选择单个视频文件 | accept 为 video 时使用 |
chooseFile |
100 | 选择文件时的最大数量限制 | accept 为 all 时使用 |
::: warning H5平台特别说明 count 值在 H5 平台的表现基于浏览器本身的规范。目前测试结果来看,只能限制单选/多选,并不能限制具体数量。并且,在实际的手机浏览器中很少有能够支持多选的。 :::
其他平台
| 选择方法 | 最大数量 | 说明 | 适用场景 |
|---|---|---|---|
chooseImage |
9 | 选择图片时的最大数量限制 | accept 为 image 时使用 |
chooseVideo |
1 | 不支持多选,只能选择单个视频文件 | accept 为 video 时使用 |
::: tip 提示
- 微信平台优先使用
chooseMedia和chooseMessageFile,具有更高的选择数量限制 - 视频选择在大多数平台都不支持多选
- 实际可选择的数量还会受到
maxCount参数的进一步限制 :::
从源码实现看,微信分支在 count 计算上做了兜底:chooseMessageFile 在未显式传入 maxCount 时默认取 100(useUpload.ts),与上表微信平台 100 的上限保持一致;而单文件选择(multiple: false)时所有平台一律 count: 1。
与 wd-upload 组件的联动
useUpload 并非孤立存在,它与 wd-upload 组件深度互通,可作为理解其用法的参照:
- 自动/手动上传:wd-upload 在
initFile中根据autoUpload决定是否立即调用startUploadFiles(wd-upload.vue),组件同时通过defineExpose暴露submit()与abort()供手动触发与中断(wd-upload.vue)。 - 构建表单数据:wd-upload 支持
buildFormData钩子,在startUploadFiles中先构建formData再传给startUpload(wd-upload.vue)。组件 demo 中给出了一个阿里云 OSS 直传的完整示例:在 Index.vue 中拼接key、OSSAccessKeyId、policy、signature等字段后resolve(formData)。 - 组件内部消费方式:wd-upload 传入
statusKey、successStatus(映射为statusCode)、uploadMethod、accept(映射为fileType)等参数调用startUpload,其成功/失败/进度事件与 hook 回调一一对应(wd-upload.vue)。
如果你希望完全复用 wd-upload 的能力但只替换 UI,直接在组件上配置 uploadMethod 自定义上传即可;如果你需要完全脱离组件、在自定义交互中实现上传,则独立调用 useUpload 是更轻量的选择。
测试与质量保障
仓库在 wd-upload.test.ts 中覆盖了与 useUpload 相关的能力验证,包括:
- 禁用状态下点击上传按钮不会触发
handleChoose(wd-upload.test.ts); - 自动上传与手动上传的触发逻辑(wd-upload.test.ts);
buildFormData钩子将自定义数据正确透传给上传流程(wd-upload.test.ts);abort中断上传方法的可用性(wd-upload.test.ts)。
这些用例从侧面印证了 useUpload 所依赖的"选择—上传—中断—表单构建"调用链是稳定且可独立验证的,你在业务中同样可以按此思路为自定义上传逻辑编写测试。
使用建议小结
- 选择文件:用
chooseFile统一封装各平台选文件差异;多选时务必结合上表平台上限设定合理的maxCount,微信端可放心使用media/file/all获得更高上限。 - 上传文件:
startUpload会帮你维护status与percent,成功判定默认以statusCode === 200为准;需要带额外参数时通过formData传入,复杂场景用uploadMethod完全接管。 - 中断控制:单任务中断直接
abort();多任务并发时持有startUpload返回的UploadTask,需要时传给abort(task)精确中断;追求"同时只传一个"可开启abortPrevious。 - 扩展名过滤:H5 端全类型可用
extension过滤;微信端仅在all/file下生效,其余平台不支持,跨端方案需业务侧二次校验。