更新记录

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 临时文件路径都只在当前会话有效,请勿跨会话保存后重新上传。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

App 端:使用 uni.chooseImage 选择图片时,按 sourceType 需要相册读取或相机权限(由宿主 App 在使用时向用户申请);使用 plus.io.chooseFile 选择系统文件时调用系统文件选择器 微信小程序端:使用 wx.chooseMedia / wx.chooseMessageFile,由微信运行时按能力向用户申请授权,插件不额外声明权限。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT协议

暂无用户评论。