image-upload

image-upload 是基于 Element Plus 的图片上传组件，支持拖拽上传、预览、删除、进度显示等功能。

🚀 基本用法

基础示例

loading

<template>
  <div>
    <!-- 基础用法 -->
    <QxsImageUpload
      v-model:file-list="fileList"
      action="https://your-upload-api.com/upload"
      :limit="4"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { QxsImageUpload } from '@qxs-bns/components'
import type { UploadFile } from 'element-plus'

const fileList = ref<UploadFile[]>([])
</script>

预设图片列表

<template>
  <QxsImageUpload
    v-model:file-list="fileList"
    action="https://your-upload-api.com/upload"
    :limit="4"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const fileList = ref([
  {
    name: 'image1.jpg',
    url: 'https://example.com/image1.jpg',
    status: 'success'
  },
  {
    name: 'image2.jpg',
    url: 'https://example.com/image2.jpg',
    status: 'success'
  }
])
</script>

📋 API 参考

Props

属性	说明	类型	默认值	必填
action	上传地址	string	-	✅
fileList	文件列表 (v-model)	UploadFile[]	[]	-
url	图片地址，支持 v-model	string	''	-
headers	请求头	object	-	-
data	上传时附带的额外参数	object	-	-
name	上传的文件字段名	string	'file'	-
size	图片大小限制（MB）	number	20	-
width	图片显示宽度（px）	number	160	-
height	图片显示高度（px）	number	90	-
limit	最大上传数量	number	1	-
accept	接受的文件类型	string	'image/jpeg,image/jpg,image/png,image/gif'	-
placeholder	上传区域提示文字	string	'上传图片'	-
notip	是否隐藏提示文字	boolean	false	-
tipText	自定义提示文字	string	-	-
disabled	是否禁用	boolean	false	-
beforeUpload	上传前的钩子函数	(file: File) => boolean | Promise<boolean>	-	-

Events

事件名	说明	回调参数
update:url	图片地址更新时触发	(url: string)
update:fileList	文件列表更新时触发	(fileList: UploadFile[])
onSuccess	上传成功时触发	(response: any, uploadFile: UploadFile, uploadFiles: UploadFiles)
remove	删除文件时触发	(file: UploadFile)

Slots

插槽名	说明	参数
default	自定义上传区域内容	-
tip	自定义提示内容	-

🎯 使用示例

完整配置示例

<template>
  <div>
    <QxsImageUpload
      v-model:file-list="fileList"
      action="https://your-api.com/upload"
      :headers="uploadHeaders"
      :data="uploadData"
      name="image"
      :size="10"
      :width="200"
      :height="150"
      :limit="5"
      accept="image/jpeg,image/png"
      placeholder="点击或拖拽上传图片"
      :tip-text="customTipText"
      :before-upload="handleBeforeUpload"
      @on-success="handleUploadSuccess"
      @remove="handleRemove"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { UploadFile, UploadFiles } from 'element-plus'

const fileList = ref<UploadFile[]>([])

// 上传配置
const uploadHeaders = {
  'Authorization': 'Bearer your-token'
}

const uploadData = {
  folder: 'images',
  category: 'product'
}

const customTipText = '支持 JPG、PNG 格式，单张图片不超过 10MB，最多上传 5 张'

// 上传前校验
const handleBeforeUpload = (file: File) => {
  const isValidType = ['image/jpeg', 'image/png'].includes(file.type)
  const isValidSize = file.size / 1024 / 1024 < 10

  if (!isValidType) {
    ElMessage.error('只能上传 JPG/PNG 格式的图片!')
    return false
  }
  if (!isValidSize) {
    ElMessage.error('图片大小不能超过 10MB!')
    return false
  }
  return true
}

// 上传成功回调
const handleUploadSuccess = (response: any, uploadFile: UploadFile, uploadFiles: UploadFiles) => {
  console.log('上传成功:', response)
  // 可以在这里处理服务器返回的数据
  if (response.code === 200) {
    uploadFile.url = response.data.url
    ElMessage.success('图片上传成功!')
  }
}

// 删除文件回调
const handleRemove = (file: UploadFile) => {
  console.log('删除文件:', file)
  ElMessage.info('图片已删除')
}
</script>

自定义上传区域

<template>
  <QxsImageUpload
    v-model:file-list="fileList"
    action="https://your-api.com/upload"
    :limit="3"
  >
    <!-- 自定义上传区域 -->
    <div class="custom-upload-area">
      <el-icon size="40px"><Plus /></el-icon>
      <p>自定义上传区域</p>
      <p>支持拖拽上传</p>
    </div>

    <!-- 自定义提示信息 -->
    <template #tip>
      <div class="custom-tip">
        <el-alert
          title="请上传清晰的产品图片，建议尺寸 800x600 像素"
          type="info"
          :closable="false"
        />
      </div>
    </template>
  </QxsImageUpload>
</template>

<style scoped>
.custom-upload-area {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  padding: 20px;
  border: 2px dashed #dcdfe6;
  border-radius: 6px;
  cursor: pointer;
  transition: border-color 0.3s;
}

.custom-upload-area:hover {
  border-color: #409eff;
}

.custom-tip {
  margin-top: 10px;
}
</style>

结合表单使用

<template>
  <el-form :model="form" :rules="rules" ref="formRef">
    <el-form-item label="产品名称" prop="name">
      <el-input v-model="form.name" />
    </el-form-item>

    <el-form-item label="产品图片" prop="images">
      <QxsImageUpload
        v-model:file-list="form.images"
        action="https://your-api.com/upload"
        :limit="5"
        @on-success="handleImageUpload"
      />
    </el-form-item>

    <el-form-item>
      <el-button type="primary" @click="submitForm">提交</el-button>
    </el-form-item>
  </el-form>
</template>

<script setup lang="ts">
import { ref, reactive } from 'vue'
import type { FormInstance, UploadFile } from 'element-plus'

const formRef = ref<FormInstance>()

const form = reactive({
  name: '',
  images: [] as UploadFile[]
})

const rules = {
  name: [
    { required: true, message: '请输入产品名称', trigger: 'blur' }
  ],
  images: [
    {
      required: true,
      validator: (rule: any, value: UploadFile[], callback: Function) => {
        if (value.length === 0) {
          callback(new Error('请至少上传一张产品图片'))
        } else {
          callback()
        }
      },
      trigger: 'change'
    }
  ]
}

const handleImageUpload = (response: any, uploadFile: UploadFile) => {
  // 处理上传成功后的逻辑
  uploadFile.url = response.data.url
}

const submitForm = async () => {
  if (!formRef.value) return

  await formRef.value.validate((valid) => {
    if (valid) {
      console.log('表单数据:', form)
      // 提交表单逻辑
    }
  })
}
</script>

🎨 样式自定义

组件支持通过 CSS 变量自定义样式：

.qxs-image-upload {
  --qxs-image-upload-width: 200px;
  --qxs-image-upload-height: 150px;
}

💡 功能特点

1. 拖拽上传：支持拖拽文件到上传区域
2. 自动校验：自动校验文件类型和大小
3. 实时进度：实时显示上传进度
4. 图片预览：支持图片预览和删除
5. 自定义样式：可自定义提示文字和样式
6. 文件校验：支持上传前的文件校验
7. 多文件上传：支持多文件批量上传
8. 响应式设计：适配不同屏幕尺寸

⚠️ 注意事项

1. 必须提供 action 属性：指定文件上传的服务器地址
2. 文件格式限制：默认只支持常见图片格式，可通过 accept 属性自定义
3. 大小限制：默认限制 20MB，可通过 size 属性调整
4. 数量限制：通过 limit 属性控制最大上传数量
5. 响应式数据：使用 v-model:file-list 进行双向绑定
6. 错误处理：组件内置基本的文件校验，建议结合 beforeUpload 进行自定义校验
7. 文件预览：组件内部会自动处理文件预览 URL 的创建和释放

🔗 相关组件

• QxsFileUpload - 通用文件上传组件
• QxsPhotoCropTool - 图片裁剪工具