更新记录
1.0.2(2025-07-17)
下载此版本
补充说明文挡
1.0.1(2025-07-17)
下载此版本
新增是否展示上传按钮的配置
1.0.0(2025-07-17)
下载此版本
新增组件
查看更多
平台兼容性
云端兼容性
uni-app(4.06)
Vue2 |
Vue3 |
Chrome |
Safari |
app-vue |
app-nvue |
Android |
iOS |
鸿蒙 |
√ |
√ |
- |
- |
- |
- |
- |
- |
- |
微信小程序 |
支付宝小程序 |
抖音小程序 |
百度小程序 |
快手小程序 |
京东小程序 |
鸿蒙元服务 |
QQ小程序 |
飞书小程序 |
快应用-华为 |
快应用-联盟 |
√ |
- |
- |
- |
- |
- |
- |
- |
- |
- |
- |
hbxw-upload 图片上传组件
hbxw-upload
是一个我项目中抽出来的 uniapp 图片上传组件,支持单图和多图上传、图片预览、自定义上传逻辑等多种功能。
特性
- 支持单图/多图上传
- 支持图片预览和删除
- 支持自定义上传逻辑
- 支持限制图片数量和大小
- 支持自动/手动上传
- 支持显示上传进度,多张的时候,显示的是张数的进度
- 支持多种图片格式
- 支持事件监听,方便扩展
使用方法
<template>
<view class="container">
<view class="demo-section">
<text class="demo-title">1. 基础用法(自动上传)</text>
<hbxw-upload
v-model="images1"
:uploadUrl="uploadUrl"
@onUploadSuccess="handleUploadSuccess"
/>
</view>
<view class="demo-section">
<text class="demo-title">2. 多图上传(最多3张)</text>
<hbxw-upload
v-model="images2"
multiple
:maxCount="3"
:uploadUrl="uploadUrl"
@onUploadedEnd="handleUploadedEnd"
/>
</view>
<view class="demo-section">
<text class="demo-title">3. 手动上传</text>
<hbxw-upload
v-model="images3"
multiple
:maxCount="5"
:autoUpload="false"
:uploadUrl="uploadUrl"
ref="manualUploadRef"
/>
<button @click="startManualUpload" size="mini" type="primary" class="manual-upload-btn">开始上传</button>
</view>
<view class="demo-section">
<text class="demo-title">4. 自定义上传</text>
<hbxw-upload
v-model="images4"
:customUpload="handleCustomUpload"
/>
</view>
<view class="demo-section">
<text class="demo-title">5. 禁用状态</text>
<hbxw-upload
v-model="images5"
disabled
/>
</view>
</view>
</template>
<script>
export default {
data() {
return {
uploadUrl: 'http://localhost:3000/upload', // 请替换为您的上传地址
images1: [],
images2: [],
images3: [],
images4: [],
images5: ['https://via.placeholder.com/150'], // 示例初始图片
};
},
methods: {
handleUploadSuccess(e) {
console.log('上传成功:', e);
uni.showToast({
title: '上传成功',
icon: 'none'
});
},
startManualUpload() {
// uni.$emit('manualUpload')
this.$refs.manualUploadRef.uploadPendingFiles();
},
async handleCustomUpload(file, index) {
console.log('自定义上传:', file, index);
// 模拟自定义上传逻辑
return new Promise((resolve, reject) => {
uni.showLoading({ title: '自定义上传中...' });
setTimeout(() => {
uni.hideLoading();
// 模拟成功,返回图片URL
const mockUrl = 'https://placehold.jp/999999/ff4400/300x300.png?text=EXAMPLE';
console.log(`文件 ${index + 1} 上传成功: ${mockUrl}`);
resolve(mockUrl);
// 模拟失败
// reject(new Error('自定义上传失败'));
}, 1500);
});
},
handleUploadedEnd(e) {
console.log('上传结束回调:', e);
}
}
}
</script>
<style lang="scss">
.container {
padding: 20rpx;
background-color: #f5f5f5;
}
.demo-section {
margin-bottom: 40rpx;
padding: 20rpx;
background-color: #fff;
border-radius: 16rpx;
}
.demo-title {
display: block;
margin-bottom: 20rpx;
font-size: 28rpx;
font-weight: bold;
}
.manual-upload-btn {
margin-top: 16rpx;
}
</style>
API
Props
属性名 |
类型 |
默认值 |
说明 |
modelValue |
Array , String |
[] |
图片列表,支持 v-model 双向绑定 |
multiple |
Boolean |
false |
是否支持多图上传 |
maxCount |
Number |
1 |
最大上传数量 |
maxSize |
Number |
2 |
最大图片大小(MB) |
beforeUpload |
Function |
null |
上传前钩子,返回 false 可阻止上传 |
customUpload |
Function |
null |
自定义上传方法 |
disabled |
Boolean |
false |
是否禁用 |
isShowUploadBtn |
Boolean |
true |
是否显示上传按钮 |
uploadOptions |
Object |
{} |
uni.uploadFile 的额外参数 |
uploadUrl |
String |
'' |
上传接口地址 |
sourceType |
Array , String |
['album', 'camera'] |
图片来源,支持相册和相机 |
autoUpload |
Boolean |
true |
是否自动上传 |
showProgress |
Boolean |
true |
是否显示上传进度 |
accept |
Array |
['jpg', 'jpeg', 'png'] |
允许的图片格式 |
preview |
Boolean |
true |
是否开启图片预览 |
chooseEventName |
String |
'chooseImage' |
选择图片事件名 |
uploadEventName |
String |
'manualUpload' |
手动上传事件名 |
Events
事件名 |
说明 |
参数 |
onRemove |
图片移除时触发 |
index |
onUploadStart |
上传开始时触发 |
{ filePath, index } |
onUploadSuccess |
上传成功时触发 |
{ filePath, index, data } |
onUploadError |
上传失败时触发 |
{ filePath, index, error } |
onProgress |
上传进度更新时触发 |
{ total, current, isUploading } |
imagesChange |
图片列表变化时触发 |
images |
onUploadedEnd |
所有文件上传结束后触发 |
{ successFiles, failedFiles, filteredFiles, uploadedUrls } |
注意事项
- 上传配置好接口url,再配合uploadOptions按后端接口文挡调好参数一般即可实现上传,如果还是有问题那你可以customUpload定义你的上传方法
- 组件有提供chooseEventName和uploadEventName,对于组件外面可以通过uni.$emit触发组件内部的事件,主要是因为部分小程序端通过ref获取组件实例不太稳定,如果你发通过组件实例调用组件方法在部分平台不生效可以试试这种方式
- 组件是我项目中抽出来的组件,可能有部分场景或者边界值没有考虑到,如果你使用中发现什么问题,欢迎留言,我看到会及时回复的
- 组件介绍页包体积显示略大,是因为有示例图片在里面,你可以放心使用,真正打包到项目中的代码是很小的