ImageUpload 图片上传

图片上传组件，支持单图/多图上传、裁剪、预览等功能。

基础用法

<script setup lang="ts">
import { ref } from 'vue'
import { ImageUpload } from '@vben/common-ui'

const imageUrl = ref('')
</script>

<template>
  <ImageUpload v-model="imageUrl" />
</template>

多图上传

<script setup lang="ts">
import { ref } from 'vue'
import { ImageUpload } from '@vben/common-ui'

const imageList = ref<string[]>([])
</script>

<template>
  <ImageUpload v-model="imageList" :limit="5" multiple />
</template>

图片裁剪

<script setup lang="ts">
import { ref } from 'vue'
import { ImageUpload } from '@vben/common-ui'

const imageUrl = ref('')
</script>

<template>
  <ImageUpload 
    v-model="imageUrl" 
    :crop="true"
    :aspect-ratio="16 / 9"
  />
</template>

限制大小和格式

<script setup lang="ts">
import { ref } from 'vue'
import { ImageUpload } from '@vben/common-ui'

const imageUrl = ref('')
</script>

<template>
  <ImageUpload 
    v-model="imageUrl"
    :max-size="2"
    :accept="['image/jpeg', 'image/png']"
  />
</template>

API

Props

参数	说明	类型	默认值
modelValue	绑定值	string | string[]	-
multiple	是否支持多选	boolean	false
limit	最大上传数量	number	1
maxSize	文件大小限制（MB）	number	5
accept	接受的文件类型	string[]	['image/*']
action	上传地址	string	/api/upload
headers	上传请求头	object	{}
data	上传额外参数	object	{}
crop	是否启用裁剪	boolean	false
aspectRatio	裁剪比例	number	1
disabled	是否禁用	boolean	false
listType	列表类型	'text' | 'picture' | 'picture-card'	'picture-card'

Events

事件名	说明	回调参数
update:modelValue	值变化时触发	(value: string | string[]) => void
change	上传状态改变时触发	(fileList: UploadFile[]) => void
success	上传成功时触发	(response: any, file: UploadFile) => void
error	上传失败时触发	(error: Error, file: UploadFile) => void
preview	点击预览时触发	(file: UploadFile) => void
remove	删除文件时触发	(file: UploadFile) => void

Slots

插槽名	说明	参数
default	自定义上传按钮	-
tip	自定义提示信息	-

完整示例

<script setup lang="ts">
import { ref } from 'vue'
import { message } from 'ant-design-vue'
import { ImageUpload } from '@vben/common-ui'
import type { UploadFile } from 'ant-design-vue'

const imageList = ref<string[]>([
  'https://example.com/image1.jpg',
  'https://example.com/image2.jpg',
])

const handleSuccess = (response: any, file: UploadFile) => {
  message.success(`${file.name} 上传成功`)
}

const handleError = (error: Error, file: UploadFile) => {
  message.error(`${file.name} 上传失败：${error.message}`)
}

const handlePreview = (file: UploadFile) => {
  console.log('预览文件：', file)
}

const handleRemove = (file: UploadFile) => {
  console.log('删除文件：', file)
}
</script>

<template>
  <ImageUpload
    v-model="imageList"
    multiple
    :limit="5"
    :max-size="2"
    :accept="['image/jpeg', 'image/png', 'image/gif']"
    action="/api/upload/image"
    :headers="{ Authorization: 'Bearer token' }"
    :data="{ folder: 'avatars' }"
    @success="handleSuccess"
    @error="handleError"
    @preview="handlePreview"
    @remove="handleRemove"
  >
    <template #tip>
      <div class="upload-tip">
        支持 JPG、PNG、GIF 格式，单个文件不超过 2MB
      </div>
    </template>
  </ImageUpload>
</template>

<style scoped>
.upload-tip {
  color: #999;
  font-size: 12px;
  margin-top: 8px;
}
</style>

自定义上传

<script setup lang="ts">
import { ref } from 'vue'
import { ImageUpload } from '@vben/common-ui'
import axios from 'axios'

const imageUrl = ref('')

const customUpload = async (file: File) => {
  const formData = new FormData()
  formData.append('file', file)
  
  const { data } = await axios.post('/api/upload', formData, {
    headers: { 'Content-Type': 'multipart/form-data' }
  })
  
  return data.url
}
</script>

<template>
  <ImageUpload 
    v-model="imageUrl"
    :custom-request="customUpload"
  />
</template>

图片压缩

<script setup lang="ts">
import { ref } from 'vue'
import { ImageUpload } from '@vben/common-ui'

const imageUrl = ref('')
</script>

<template>
  <ImageUpload 
    v-model="imageUrl"
    :compress="true"
    :compress-quality="0.8"
    :compress-max-width="1920"
    :compress-max-height="1080"
  />
</template>

注意事项

注意

1. 上传的图片会自动转换为 Base64 或返回 URL
2. 多图上传时，返回的是数组格式
3. 裁剪功能需要额外引入 cropperjs 依赖
4. 建议设置合理的文件大小限制，避免上传过大的图片

提示

• 可以通过 accept 属性限制上传的文件类型
• 使用 maxSize 属性限制文件大小
• 启用 compress 可以自动压缩图片，减少上传时间

相关链接

• FileUpload 文件上传
• 上传工具类
• 在线示例