vue3+element-plus 基于el-upload二次封装的ProUploadImg图片上传组件

ProUploadImg 图片上传组件

实现效果

图片预览效果

组件介绍

ProUploadImg 是一个基于 Element Plus 封装的图片上传组件，提供了图片预览、删除、大小限制、尺寸限制等功能。该组件支持单图和多图上传，并且提供了丰富的配置选项。

功能特点

• 支持单图/多图上传
• 支持图片预览
• 支持图片删除
• 支持文件类型限制
• 支持文件大小限制
• 支持图片尺寸限制
• 支持自定义上传提示
• 支持禁用状态
• 支持自定义提示信息

代码实现

/** 
  * 图片上传组件
  * 基于 Element Plus的上传组件封装
  * 支持图片预览、删除、大小限制、尺寸限制等功能
  */

 

 

Props 属性

参数	说明	类型	默认值	必填
action	上传地址	string	-	是
headers	请求头	object	{}	否
multiple	是否支持多选	boolean	false	否
limit	最大上传数量，0表示不限制	number	0	否
accept	接受的文件类型	string	'.jpg,.png,.jpeg'	否
maxSize	文件大小限制	number	2	否
sizeUnit	文件大小单位（KB/MB）	string	'MB'	否
width	图片宽度限制	number	0	否
height	图片高度限制	number	0	否
uploadText	上传提示文字	string	'上传图片'	否
tip	上传提示说明	string	''	否
disabled	是否禁用	boolean	false	否
fileList	初始文件列表	array	[]	否

事件

事件名	说明	回调参数
success	上传成功时触发	(response: object, uploadFile: object, uploadFiles: array)
error	上传失败时触发	(error: Error, uploadFile: object, uploadFiles: array)
exceed	超出限制时触发	(files: array, uploadFiles: array)
remove	移除图片时触发	(file: object)

插槽

名称	描述
default	自定义上传按钮内容
tip	提示说明文字

 使用示例

文件限制说明

文件类型限制

默认支持 .jpg、.png、.jpeg 格式，可通过 accept 属性自定义。

文件大小限制

• 默认不限制文件大小
• 可通过 maxSize 属性自定义大小
• 支持 KB 和 MB 两种单位，通过 sizeUnit 属性设置

图片尺寸限制

• 可通过 width 和 height 属性限制图片尺寸
• 支持同时限制宽高或单独限制宽度/高度
• 不设置则不做限制

样式说明

组件默认样式：

• 图片卡片尺寸：100px × 100px
• 图片圆角：6px
• 删除按钮位置：右上角
• 预览遮罩：半透明黑色背景
• 上传按钮：居中显示加号图标和提示文字

注意事项

• 上传地址（action）为必填项
• 文件大小限制的单位默认为 MB
• 图片尺寸限制支持同时限制宽高或单独限制
• 上传接口返回数据格式需要符合以下规范（如果不符合规范请调整组件封装的代码）：

{
  code: 10000,  // 成功状态码
  data: {
    fileUrl: '文件地址',
  },
  msg: '提示信息'
}

常见问题

上传失败如何处理？

• 检查上传地址是否正确
• 检查网络连接是否正常
• 检查文件是否符合限制条件

如何自定义上传提示？

• 使用 uploadText 属性设置上传按钮文字
• 使用 tip 属性设置提示说明文字

如何限制文件类型？

• 使用 accept 属性设置允许的文件类型
• 例如：.jpg,.png 表示只允许 jpg 和 png 格式

如何禁用上传功能？

• 使用 disabled 属性设置为 true 即可禁用

fileList没有同步更新？

• 组件中使用了defineModel()，defineModel()仅在vue 3.4+ 版本中可用
• 如果版本较低可以升版本或者用update:fileList进行替代

  const props = defineProps({
    /** 初始文件列表 */
    fileList: {
      type: Array,
      default: () => [],
    },
  });
  const fileList = ref([]);
  // 监听 props.fileList 变化
  watch(
    () => props.fileList,
    (newVal) => {
      if (newVal) {
        fileList.value = newVal;
      }
    },
    { immediate: true },
  );  
  const emit = defineEmits(['update:fileList']);
  /**
   * 更新文件列表并触发更新事件
   */
  const updateFileList = () => {
    emit('update:fileList', fileList.value);
  };
  const handleSuccess = (response, uploadFile, uploadFiles) => {
    // 上传完成后更新文件列表
    updateFileList();
  };
  const handleRemove = (file, index) => {
    // 移除图片后更新文件列表
    updateFileList();
  };