更新记录
1.0.0(2026-11-18)
下载此版本
1.0.0(2026-11-18)
- 初始版本
- 支持 Vue2/Vue3、HBuilderX/CLI、H5/App/微信小程序
- 提供 JS SDK 与 easycom 上传组件
- 支持自动/手动上传、进度、取消、重试、并发、数量与大小限制、默认样式和自定义插槽
平台兼容性
uni-app(5.03)
| Vue2 |
Vue3 |
Chrome |
Safari |
app-vue |
app-nvue |
Android |
iOS |
鸿蒙 |
| √ |
√ |
√ |
√ |
√ |
- |
√ |
√ |
- |
| 微信小程序 |
支付宝小程序 |
抖音小程序 |
百度小程序 |
快手小程序 |
京东小程序 |
鸿蒙元服务 |
QQ小程序 |
飞书小程序 |
小红书小程序 |
快应用-华为 |
快应用-联盟 |
| √ |
- |
- |
- |
- |
- |
- |
- |
- |
- |
- |
- |
其他
| 多语言 |
暗黑模式 |
宽屏模式 |
蒸汽模式 |
| × |
× |
√ |
× |
Easy Upload - 跨端文件上传
跨端文件上传插件,兼容 Vue2/Vue3、HBuilderX/CLI 项目以及 H5、Android、iOS、微信小程序,内置上传列表 UI,无需原生插件和额外打包配置。
特性
- 自动上传 / 手动上传(
autoUpload)
- 图片、文件、音视频选择;支持数量、大小、自定义校验
- 并发上传、进度、取消、失败重试、清空
- 默认上传样式 + 具名插槽完全自定义
v-model 双向绑定文件列表
- 纯 JS SDK:可在非组件场景直接调用
- 所有能力基于
uni.chooseImage / uni.uploadFile / H5 原生 XHR,无 UTS/原生依赖
安装
在 HBuilderX 插件市场导入本插件后,目录位于 uni_modules/liwei-easy-upload。组件遵循 easycom 约定,放置后即可在页面直接使用 <easy-upload>,无需 import 和注册。
CLI 项目请将插件放到 src/uni_modules/liwei-easy-upload。
基础用法(Vue3 + script setup)
<script setup>
import { ref, shallowRef } from 'vue'
const uploadUrl = 'https://example.com/upload'
const autoFiles = ref([])
const manualFiles = ref([])
const uploader = shallowRef(null)
function uploadManual() {
uploader.value && uploader.value.upload()
}
function onSuccess(result) {
console.log(result.data)
}
function onFail(error) {
console.error(error)
}
</script>
<template>
<view class="page">
<view class="section">
<view class="section-title">自动上传图片</view>
<easy-upload
v-model="autoFiles"
:action="uploadUrl"
name="file"
file-type="image"
:max-count="6"
:max-size="5 * 1024 * 1024"
:form-data="{ from: 'easy-upload' }"
:auto-upload="true"
:concurrency="2"
add-text="添加图片"
@success="onSuccess"
@fail="onFail"
/>
</view>
<view class="section">
<view class="section-title">手动上传文件</view>
<easy-upload
ref="uploader"
v-model="manualFiles"
:action="uploadUrl"
name="file"
file-type="file"
accept="*/*"
:max-count="3"
:auto-upload="false"
add-text="选择文件"
@success="onSuccess"
@fail="onFail"
/>
<button size="mini" type="primary" @click="uploadManual">开始上传</button>
</view>
</view>
</template>
Vue2 中使用 Options API 同样可用,v-model、ref 调用方式一致。
Props
| 参数 |
类型 |
默认值 |
说明 |
modelValue / value |
Array |
[] |
文件列表,v-model 绑定 |
action |
String |
'' |
上传接口地址 |
name |
String |
'file' |
表单中文件字段名 |
formData |
Object |
{} |
额外表单字段 |
header |
Object |
{} |
请求头 |
timeout |
Number |
60000 |
超时时间(ms) |
autoUpload |
Boolean |
true |
选择后是否自动上传 |
maxCount |
Number |
9 |
最大文件数 |
maxSize |
Number |
0 |
单文件大小上限(字节),0 不限 |
minSize |
Number |
0 |
单文件大小下限(字节) |
fileType |
String |
'image' |
image / file / media / all |
multiple |
Boolean |
true |
是否多选 |
sourceType |
Array |
['album','camera'] |
来源 |
sizeType |
Array |
['compressed','original'] |
图片尺寸 |
mediaType |
Array |
根据 fileType |
微信小程序 chooseMedia 类型 |
accept |
String |
根据 fileType |
H5 input accept |
extension |
Array |
[] |
文件后缀过滤(微信 chooseMessageFile / App chooseFile) |
messageFileType |
String |
'file' |
微信 chooseMessageFile 类型:all / file / image / video |
appFileTitle |
String |
'选择文件' |
App 文件选择器标题 |
appFileFilter |
String |
'*' |
App 文件选择器过滤,如 pdf、docx |
appCopyToSandbox |
Boolean |
true |
App 选择系统文件后是否复制到应用沙箱再上传 |
withCredentials |
Boolean |
false |
H5 XHR 是否携带凭据 |
concurrency |
Number |
1 |
并发上传数 |
showRemove |
Boolean |
true |
是否显示删除按钮 |
disabled |
Boolean |
false |
是否禁用 |
addText |
String |
'上传' |
添加按钮文案 |
successStatus |
Array |
[200] |
视为成功的 HTTP 状态码 |
validate |
Function |
null |
自定义校验,返回 false 或错误文案 |
beforeChoose |
Function |
null |
选择前钩子,返回 false 阻止 |
beforeUpload |
Function |
null |
上传前钩子,可返回 Promise/配置 |
processResponse |
Function |
null |
自定义处理响应 |
nameFn |
Function |
null |
自定义文件名 |
rootClass / rootStyle / listClass / itemClass / itemStyle / previewClass / previewStyle / addClass / addStyle / removeClass |
String/Object |
— |
自定义样式 |
Events
| 事件 |
参数 |
说明 |
select |
files |
选择并通过校验 |
change |
files |
文件列表变化 |
progress |
file, progress |
单个文件进度 |
start |
files |
开始上传 |
success |
result, file, index |
上传成功 |
fail |
error, file, index |
上传失败 |
choose-error |
error |
选择失败 |
cancel |
error |
用户取消选择 |
oversize |
file, reason |
校验不通过 |
abort |
file |
取消上传 |
remove |
file, index |
删除文件 |
preview |
file, index |
点击预览 |
方法(ref 调用)
| 方法 |
说明 |
upload() |
手动上传所有待上传文件 |
abort(file?) |
取消指定文件或全部上传 |
clear() |
清空列表并取消上传 |
插槽
item:自定义文件项,参数为 { file, index, remove, retry }
add:自定义添加按钮
remove-icon:自定义删除图标
<easy-upload v-model="files" action="https://example.com/upload">
<template #item="{ file, remove, retry }">
<view class="my-item" @click="retry(file)">
<text>{{ file.name }}</text>
<text v-if="file.status === 'error'" @click.stop="remove(file)">重试/删除</text>
</view>
</template>
</easy-upload>
JS SDK
import upload, {
chooseFiles,
uploadFile,
uploadBatch
} from '@/uni_modules/liwei-easy-upload/js_sdk/index.js'
const files = await chooseFiles({ count: 5, fileType: 'file' })
const task = uploadFile({
url: 'https://example.com/upload',
filePath: files[0].path,
name: 'file',
onProgress: console.log
})
const result = await task.promise
// task.abort()
await uploadBatch(files, {
url: 'https://example.com/upload',
concurrency: 2,
onProgress: (file, p) => console.log(p)
})
Vue 入口安装(可选):
// Vue2: Vue.use(upload); Vue3: app.use(upload)
import upload from '@/uni_modules/liwei-easy-upload/js_sdk/index.js'
平台说明
- H5:图片使用 blob URL,文件选择用原生
input,上传走 XMLHttpRequest,需后端开启 CORS。
- App(Android/iOS):图片使用
uni.chooseImage;fileType=file|all 且运行时支持时使用 plus.io.chooseFile,并自动复制到应用沙箱(可关闭)。上传走 uni.uploadFile,无需原生插件。
- 微信小程序:图片/视频使用
wx.chooseMedia,fileType=file 使用 wx.chooseMessageFile(基础库 2.5.0+);需在小程序后台配置 uploadFile 合法域名。
注意事项
action 必须在组件上传前配置;手动上传通过 ref.upload() 触发。
- 小程序需配置
uploadFile 合法域名;H5 需后端开启 CORS。
- H5 的 blob URL、小程序临时路径、App 临时文件路径都只在当前会话有效,请勿跨会话保存后重新上传。