wot-design-uni useUpload 组合式 API 实战指南:文件选择、上传与中断控制

原创2026-10-13 14:01:401,892 阅读
文章标签:UI组件移动开发小程序设计系统跨平台前端

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 内部闭环完成:

  1. 调用 startUpload 时立即将 file[statusKey] 置为 LOADING;
  2. onSuccess 分支将状态改写为 SUCCESS 并清空 currentTask;
  3. onError 分支将状态改写为 FAIL,同时写入 file.error = error.errMsg 并清空 currentTask;
  4. 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 相关的能力验证,包括:

这些用例从侧面印证了 useUpload 所依赖的"选择—上传—中断—表单构建"调用链是稳定且可独立验证的,你在业务中同样可以按此思路为自定义上传逻辑编写测试。

使用建议小结

  1. 选择文件:用 chooseFile 统一封装各平台选文件差异;多选时务必结合上表平台上限设定合理的 maxCount,微信端可放心使用 media / file / all 获得更高上限。
  2. 上传文件:startUpload 会帮你维护 status 与 percent,成功判定默认以 statusCode === 200 为准;需要带额外参数时通过 formData 传入,复杂场景用 uploadMethod 完全接管。
  3. 中断控制:单任务中断直接 abort();多任务并发时持有 startUpload 返回的 UploadTask,需要时传给 abort(task) 精确中断;追求"同时只传一个"可开启 abortPrevious。
  4. 扩展名过滤:H5 端全类型可用 extension 过滤;微信端仅在 all / file 下生效,其余平台不支持,跨端方案需业务侧二次校验。
登录后查看全文
wot-design-uni