更新记录

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获取组件实例不太稳定,如果你发通过组件实例调用组件方法在部分平台不生效可以试试这种方式
  • 组件是我项目中抽出来的组件,可能有部分场景或者边界值没有考虑到,如果你使用中发现什么问题,欢迎留言,我看到会及时回复的
  • 组件介绍页包体积显示略大,是因为有示例图片在里面,你可以放心使用,真正打包到项目中的代码是很小的

隐私、权限声明

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

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

插件不采集任何数据

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

许可协议

MIT协议

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问