Upload 上传

Upload 用于通过点击或拖拽上传文件。VISTA B 直接使用 Element Plus 的 el-upload，适合头像上传、图片墙、附件列表、手动提交和目录上传等场景。

基础用法

通过默认插槽可以自定义上传按钮，通过 tip 插槽添加提示文案。可设置 limit 和 on-exceed 限制上传文件个数，也可通过 before-remove 阻止文件移除。

jpg/png files with a size less than 500KB.

element-plus-logo.svg
element-plus-logo2.svg

未操作

vue

<el-upload
  v-model:file-list="fileList"
  action="#"
  multiple
  :limit="3"
  :on-exceed="handleExceed"
>
  <el-button type="primary">Click to upload</el-button>
  <template #tip>
    <div class="el-upload__tip">jpg/png files with a size less than 500KB.</div>
  </template>
</el-upload>

覆盖前一个文件

设置 limit 和 on-exceed 后，可以在用户重新选择文件时自动替换前一个文件。

limit 1 file, new file will cover the old file

vue

<el-upload
  ref="upload"
  action="#"
  :limit="1"
  :on-exceed="handleExceed"
  :auto-upload="false"
>
  <template #trigger>
    <el-button type="primary">select file</el-button>
  </template>
  <el-button type="success" @click="submitUpload">upload to server</el-button>
</el-upload>

用户头像

在 before-upload 钩子中可以限制上传文件的格式和大小。下面示例只允许上传小于 2MB 的 JPG/PNG 图片。

vue

<el-upload
  class="avatar-uploader"
  action="#"
  :show-file-list="false"
  :on-success="handleAvatarSuccess"
  :before-upload="beforeAvatarUpload"
>
  <img v-if="imageUrl" :src="imageUrl" class="avatar" />
  <el-icon v-else class="avatar-uploader-icon"><Plus /></el-icon>
</el-upload>

照片墙

使用 list-type="picture-card" 可以把文件列表展示为照片墙。点击缩略图时可以通过 on-preview 展示大图。

vue

<el-upload
  v-model:file-list="fileList"
  action="#"
  list-type="picture-card"
  :on-preview="handlePictureCardPreview"
>
  <el-icon><Plus /></el-icon>
</el-upload>

自定义缩略图

通过 file 插槽可以自定义文件缩略图内容和操作按钮。

vue

<el-upload action="#" list-type="picture-card" :auto-upload="false">
  <el-icon><Plus /></el-icon>
  <template #file="{ file }">
    <img class="el-upload-list__item-thumbnail" :src="file.url" alt="" />
  </template>
</el-upload>

图片列表缩略图

设置 list-type="picture" 后，文件列表会以带缩略图的列表形式展示。

jpg/png files with a size less than 500kb

food.jpeg
food2.jpeg

vue

<el-upload
  v-model:file-list="fileList"
  action="#"
  list-type="picture"
>
  <el-button type="primary">Click to upload</el-button>
</el-upload>

上传文件列表控制

通过 on-change 可以控制上传文件列表。下面示例保留最近 3 个文件。

Only keep the latest 3 files.

food.jpeg
food2.jpeg

vue

<el-upload
  v-model:file-list="fileList"
  action="#"
  :on-change="handleChange"
>
  <el-button type="primary">Click to upload</el-button>
</el-upload>

拖拽上传

设置 drag 后可以拖拽文件到上传区域，也可以点击区域选择文件。

Drop file here or click to upload

jpg/png files with a size less than 500kb

vue

<el-upload drag action="#" multiple>
  <el-icon class="el-icon--upload"><UploadFilled /></el-icon>
  <div class="el-upload__text">
    Drop file here or <em>click to upload</em>
  </div>
</el-upload>

上传目录

设置 directory 后可以选择文件夹。选择文件夹后，文件夹内的文件会被扁平化处理。

Drop directory here or click to upload

vue

<el-upload
  drag
  action="#"
  directory
  multiple
>
  <el-icon class="el-icon--upload"><UploadFilled /></el-icon>
  <div class="el-upload__text">Drop directory here or click to upload</div>
</el-upload>

手动上传

设置 auto-upload="false" 后，文件选择不会自动上传，需要调用组件实例的 submit 方法。

jpg/png files with a size less than 500kb

vue

<script setup>
import { ref } from 'vue'

const uploadRef = ref()

const submitUpload = () => {
  uploadRef.value?.submit()
}
</script>

<template>
  <el-upload ref="uploadRef" action="#" :auto-upload="false">
    <template #trigger>
      <el-button type="primary">select file</el-button>
    </template>
    <el-button type="success" @click="submitUpload">upload to server</el-button>
  </el-upload>
</template>

API

Upload 属性

属性	说明	类型	默认值
`action`	请求 URL	`string`	`#`
`headers`	设置上传请求头	`object`	空
`method`	上传请求方法	`string`	`post`
`multiple`	是否支持多选文件	`boolean`	`false`
`data`	上传时附带的额外参数，支持对象、函数或 Promise	`object` / `function` / `Promise`	`{}`
`name`	上传的文件字段名	`string`	`file`
`with-credentials`	是否发送 cookie 凭证信息	`boolean`	`false`
`show-file-list`	是否显示已上传文件列表	`boolean`	`true`
`drag`	是否启用拖拽上传	`boolean`	`false`
`accept`	接受上传的文件类型	`string`	空
`crossorigin`	图片相关原生 `crossorigin` 属性	`anonymous` / `use-credentials` / `''`	空
`on-preview`	点击文件列表中已上传文件时的钩子	`function`	空
`on-remove`	文件列表移除文件时的钩子	`function`	空
`on-success`	文件上传成功时的钩子	`function`	空
`on-error`	文件上传失败时的钩子	`function`	空
`on-progress`	文件上传过程中的钩子	`function`	空
`on-change`	文件状态改变时的钩子，添加文件、上传成功和上传失败时都会调用	`function`	空
`on-exceed`	文件数量超出限制时的钩子	`function`	空
`before-upload`	上传文件前的钩子，返回 `false` 或 rejected Promise 会停止上传	`function`	空
`before-remove`	删除文件前的钩子，返回 `false` 或 rejected Promise 会停止删除	`function`	空
`file-list` / `v-model:file-list`	默认上传文件列表	`array`	`[]`
`list-type`	文件列表类型	`text` / `picture` / `picture-card`	`text`
`auto-upload`	是否自动上传文件	`boolean`	`true`
`http-request`	覆盖默认 XHR 行为，自定义上传请求	`function`	默认 XHR
`disabled`	是否禁用上传	`boolean`	`false`
`limit`	允许上传文件的最大数量	`number`	空
`directory`	是否支持上传文件夹	`boolean`	`false`

Upload 插槽

插槽	说明
`default`	自定义默认内容
`trigger`	触发文件选择框的内容
`tip`	提示说明文字
`file`	缩略图模板内容，参数为 `{ file, index }`

Upload 方法

方法名	说明	类型
`abort`	取消上传请求；传入文件时取消对应文件，不传时取消所有文件	`(file?: UploadFile) => void`
`submit`	手动上传文件列表	`() => void`
`clearFiles`	清空已上传文件列表，不支持在 `before-upload` 中调用	`(status?: UploadStatus[]) => void`
`handleStart`	手动选择文件	`(rawFile: UploadRawFile) => void`
`handleRemove`	手动移除文件	`(file: UploadFile \| UploadRawFile) => void`

使用提醒

真实业务中需要把 action、headers、data、with-credentials 与后端接口契约对齐。需要在文档或本地演示中避免真实请求时，可以像本页一样使用 http-request 接管上传行为。

Upload 上传 ​

基础用法 ​

覆盖前一个文件 ​

用户头像 ​

照片墙 ​

自定义缩略图 ​

图片列表缩略图 ​

上传文件列表控制 ​

拖拽上传 ​

上传目录 ​

手动上传 ​

API ​

Upload 属性 ​

Upload 插槽 ​

Upload 方法 ​

使用提醒 ​

Upload 上传

基础用法

覆盖前一个文件

用户头像

照片墙

自定义缩略图

图片列表缩略图

上传文件列表控制

拖拽上传

上传目录

手动上传

API

Upload 属性

Upload 插槽

Upload 方法

使用提醒