Upload 上传

文件上传组件，提供单图上传、多图上传和文件上传三种组件。

组件介绍

vue3-element-admin 提供了三个上传组件，满足不同的业务场景：

SingleImageUpload：单图上传，适用于头像、封面图等场景
MultiImageUpload：多图上传，适用于相册、商品图片等场景
FileUpload：文件上传，适用于文档、附件等场景

SingleImageUpload 单图上传

基本用法

vue

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

<script setup lang="ts">
const imageUrl = ref('https://example.com/image.jpg')
</script>

限制图片格式

vue

<template>
  <SingleImageUpload
    v-model="imageUrl"
    accept=".png,.jpg,.jpeg"
  />
</template>

<script setup lang="ts">
const imageUrl = ref('')
</script>

自定义尺寸

vue

<template>
  <SingleImageUpload
    v-model="imageUrl"
    :style="{ width: '200px', height: '200px' }"
  />
</template>

限制文件大小

vue

<template>
  <SingleImageUpload
    v-model="imageUrl"
    :max-file-size="5"
  />
</template>

<script setup lang="ts">
// 限制图片大小不超过 5MB
const imageUrl = ref('')
</script>

Props

参数	说明	类型	默认值
`modelValue`	图片URL（支持 v-model）	`string`	`''`
`accept`	接受的图片格式	`string`	`'image/*'`
`maxFileSize`	最大文件大小（单位：MB）	`number`	`10`
`name`	上传文件的参数名	`string`	`'file'`
`data`	上传时附带的额外参数	`object`	`{}`
`style`	自定义样式（宽度、高度等）	`object`	`{ width: '150px', height: '150px' }`

Events

事件名	说明	回调参数
`update:modelValue`	值变化时触发	`(value: string)`

功能特性

✅ 图片预览（点击图片放大查看）
✅ 删除图片（点击删除按钮）
✅ 格式校验（支持 MIME 类型和扩展名）
✅ 大小限制（可自定义最大文件大小）
✅ 上传进度（自动显示上传进度）
✅ 错误提示（格式或大小不符时提示）

MultiImageUpload 多图上传

基本用法

vue

<template>
  <MultiImageUpload v-model="imageUrls" />
</template>

<script setup lang="ts">
const imageUrls = ref<string[]>([
  'https://example.com/image1.jpg',
  'https://example.com/image2.jpg'
])
</script>

限制上传数量

vue

<template>
  <MultiImageUpload
    v-model="imageUrls"
    :limit="5"
  />
</template>

<script setup lang="ts">
// 最多上传 5 张图片
const imageUrls = ref<string[]>([])
</script>

限制图片格式和大小

vue

<template>
  <MultiImageUpload
    v-model="imageUrls"
    accept=".png,.jpg,.jpeg,.gif"
    :max-file-size="10"
    :limit="9"
  />
</template>

<script setup lang="ts">
const imageUrls = ref<string[]>([])
</script>

Props

参数	说明	类型	默认值
`modelValue`	图片URL数组（支持 v-model）	`string[]`	`[]`
`limit`	最大上传数量	`number`	`10`
`accept`	接受的图片格式	`string`	`'image/*'`
`maxFileSize`	单个文件最大大小（单位：MB）	`number`	`10`
`name`	上传文件的参数名	`string`	`'file'`
`data`	上传时附带的额外参数	`object`	`{}`

Events

事件名	说明	回调参数
`update:modelValue`	值变化时触发	`(value: string[])`

功能特性

✅ 多图上传（支持同时选择多个文件）
✅ 图片预览（点击图片放大查看，支持切换）
✅ 删除图片（点击删除按钮删除指定图片）
✅ 数量限制（达到限制后隐藏上传按钮）
✅ 拖拽排序（可拖拽调整图片顺序）
✅ 格式校验（支持 MIME 类型和扩展名）
✅ 大小限制（每个文件都会校验大小）
✅ 超出提示（超出数量限制时提示）

FileUpload 文件上传

基本用法

vue

<template>
  <FileUpload v-model="fileList" />
</template>

<script setup lang="ts">
interface FileInfo {
  name: string
  url: string
}

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

预填充文件列表

vue

<template>
  <FileUpload v-model="fileList" />
</template>

<script setup lang="ts">
const fileList = ref<FileInfo[]>([
  {
    name: '用户手册.pdf',
    url: 'https://example.com/manual.pdf'
  },
  {
    name: '需求文档.docx',
    url: 'https://example.com/requirements.docx'
  }
])
</script>

限制上传数量和类型

vue

<template>
  <FileUpload
    v-model="fileList"
    :limit="5"
    accept=".pdf,.doc,.docx"
  />
</template>

<script setup lang="ts">
const fileList = ref<FileInfo[]>([])
</script>

自定义按钮文本

vue

<template>
  <FileUpload
    v-model="fileList"
    upload-btn-text="选择文件"
  />
</template>

限制文件大小

vue

<template>
  <FileUpload
    v-model="fileList"
    :max-file-size="20"
    :limit="10"
  />
</template>

<script setup lang="ts">
// 单个文件最大 20MB，最多上传 10 个文件
const fileList = ref<FileInfo[]>([])
</script>

Props

参数	说明	类型	默认值
`modelValue`	文件列表（支持 v-model）	`FileInfo[]`	`[]`
`limit`	最大上传数量	`number`	`10`
`accept`	接受的文件类型	`string`	`'*'`
`maxFileSize`	单个文件最大大小（单位：MB）	`number`	`10`
`uploadBtnText`	上传按钮文本	`string`	`'上传文件'`
`name`	上传文件的参数名	`string`	`'file'`
`data`	上传时附带的额外参数	`object`	`{}`
`style`	自定义样式	`object`	`{ width: '300px' }`

FileInfo 类型

typescript

interface FileInfo {
  name: string    // 文件名
  url: string     // 文件地址
}

Events

事件名	说明	回调参数
`update:modelValue`	值变化时触发	`(value: FileInfo[])`

功能特性

✅ 多文件上传（支持同时选择多个文件）
✅ 文件下载（点击文件名下载）
✅ 删除文件（点击删除按钮）
✅ 上传进度（显示上传进度条）
✅ 数量限制（达到限制后禁用上传按钮）
✅ 格式校验（支持 MIME 类型和扩展名）
✅ 大小限制（每个文件都会校验大小）
✅ 文件预览（显示文件名和图标）

完整示例

表单中使用

vue

<template>
  <el-form :model="form" label-width="120px">
    <el-form-item label="头像">
      <SingleImageUpload v-model="form.avatar" />
    </el-form-item>

    <el-form-item label="商品图片">
      <MultiImageUpload
        v-model="form.images"
        :limit="5"
      />
    </el-form-item>

    <el-form-item label="附件">
      <FileUpload
        v-model="form.files"
        :limit="3"
        accept=".pdf,.doc,.docx"
      />
    </el-form-item>

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

<script setup lang="ts">
interface FormData {
  avatar: string
  images: string[]
  files: FileInfo[]
}

const form = reactive<FormData>({
  avatar: '',
  images: [],
  files: []
})

function handleSubmit() {
  console.log('表单数据：', form)
  // 提交表单...
}
</script>

自定义样式

vue

<template>
  <div>
    <!-- 大尺寸单图上传 -->
    <SingleImageUpload
      v-model="largeImage"
      :style="{ width: '300px', height: '300px' }"
    />

    <!-- 小尺寸单图上传 -->
    <SingleImageUpload
      v-model="smallImage"
      :style="{ width: '80px', height: '80px' }"
    />
  </div>
</template>

<script setup lang="ts">
const largeImage = ref('')
const smallImage = ref('')
</script>

<style scoped>
/* 可以通过 CSS 进一步自定义样式 */
:deep(.el-upload) {
  border-radius: 8px;
}
</style>

常见文件类型

图片格式

typescript

// 所有图片格式
accept="image/*"

// 指定图片格式
accept=".jpg,.jpeg,.png,.gif,.bmp,.webp"

// MIME 类型
accept="image/jpeg,image/png,image/gif"

文档格式

typescript

// Word 文档
accept=".doc,.docx"

// Excel 表格
accept=".xls,.xlsx"

// PDF 文档
accept=".pdf"

// 所有文档
accept=".doc,.docx,.xls,.xlsx,.pdf"

压缩包

typescript

accept=".zip,.rar,.7z"

所有文件

typescript

accept="*"

上传流程

选择文件：用户点击上传按钮选择文件
格式校验：校验文件格式是否符合 accept 规则
大小校验：校验文件大小是否超过 maxFileSize 限制
文件上传：调用后端接口上传文件
更新数据：上传成功后更新 modelValue
显示文件：在界面上显示已上传的文件

注意事项

1. 文件格式校验

组件会进行两次格式校验：

浏览器层面：accept 属性限制文件选择器中可选的文件类型
代码层面：上传前再次校验文件的实际类型

2. 文件大小限制

单位为 MB（兆字节）
每个文件都会单独校验
超过限制会阻止上传并提示用户

3. 数量限制

SingleImageUpload 固定为 1 张
MultiImageUpload 和 FileUpload 可通过 limit 属性设置
达到限制后会禁用上传功能

4. 上传接口

组件默认调用 FileAPI.upload() 接口，请确保：

后端接口已正确配置
接口返回格式符合要求
正确处理跨域和认证

5. v-model 绑定

typescript

// SingleImageUpload - 绑定字符串
const imageUrl = ref<string>('')

// MultiImageUpload - 绑定字符串数组
const imageUrls = ref<string[]>([])

// FileUpload - 绑定对象数组
const files = ref<FileInfo[]>([])

常见问题

1. 上传失败

可能原因：

后端接口未启动或地址错误
文件格式不正确
文件大小超出限制
网络连接问题

解决方案：

检查浏览器控制台的网络请求
确认后端接口正常
检查文件格式和大小

2. 图片不显示

可能原因：

图片URL不正确
跨域问题
图片已被删除

解决方案：

检查图片URL是否正确
配置服务器允许跨域
确认图片文件存在

3. 删除功能无效

可能原因：

后端删除接口未实现
接口返回错误

解决方案：

实现 FileAPI.delete() 接口
检查接口返回值

Upload 上传 ​

组件介绍 ​

SingleImageUpload 单图上传 ​

基本用法 ​

限制图片格式 ​

自定义尺寸 ​

限制文件大小 ​

Props ​

Events ​

功能特性 ​

MultiImageUpload 多图上传 ​

基本用法 ​

限制上传数量 ​

限制图片格式和大小 ​

Props ​

Events ​

功能特性 ​

FileUpload 文件上传 ​

基本用法 ​

预填充文件列表 ​

限制上传数量和类型 ​

自定义按钮文本 ​

限制文件大小 ​

Props ​

FileInfo 类型 ​

Events ​

功能特性 ​

完整示例 ​

表单中使用 ​

自定义样式 ​

常见文件类型 ​

图片格式 ​

文档格式 ​

压缩包 ​

所有文件 ​

上传流程 ​

注意事项 ​

1. 文件格式校验 ​

2. 文件大小限制 ​

3. 数量限制 ​

4. 上传接口 ​

5. v-model 绑定 ​

常见问题 ​

1. 上传失败 ​

2. 图片不显示 ​

3. 删除功能无效 ​

相关链接 ​

Upload 上传

组件介绍

SingleImageUpload 单图上传

基本用法

限制图片格式

自定义尺寸

限制文件大小

Props

Events

功能特性

MultiImageUpload 多图上传

基本用法

限制上传数量

限制图片格式和大小

Props

Events

功能特性

FileUpload 文件上传

基本用法

预填充文件列表

限制上传数量和类型

自定义按钮文本

限制文件大小

Props

FileInfo 类型

Events

功能特性

完整示例

表单中使用

自定义样式

常见文件类型

图片格式

文档格式

压缩包

所有文件

上传流程

注意事项

1. 文件格式校验

2. 文件大小限制

3. 数量限制

4. 上传接口

5. v-model 绑定

常见问题

1. 上传失败

2. 图片不显示

3. 删除功能无效

相关链接