Upload 附件上传

avue-upload 处理文件选择、上传及结果回显。默认绑定 URL 数组；使用 dataType="object" 保存名称与地址对象，dataType="json" 保存序列化字符串。单图 listType="picture-img" 输出字符串地址。

基础用法

效果预览可直接操作下方示例

本例使用页面内模拟接口，选择图片可预览并观察绑定值，不会向外部服务发送文件。业务接入时将 action 换成自己的上传接口，并移除模拟代码。

正在加载示例…

<template>
  <avue-upload v-model="files" type="upload" :action="baseUrl + '/upload'" :props-http="{ res: 'data' }"
    list-type="picture-card" multiple accept="image/png,image/jpeg" :limit="3" :file-size="1024"
    :upload-error="onError" />
  <p>选择不超过 1 MB 的 PNG/JPEG 图片，最多 3 张；只在当前页面生成预览地址。</p>
  <pre>{{ JSON.stringify({ files, error }, null, 2) }}</pre>
</template>

<script setup>
import { onBeforeUnmount, ref } from 'vue';
import { useDictionaryMock } from '../../form/_shared/useDictionaryMock';
const files = ref([]);
const error = ref('');
const previewUrls = [];
const { baseUrl } = useDictionaryMock(({ query }) => {
  const file = query.get('file');
  const url = URL.createObjectURL(file);
  previewUrls.push(url);
  return { data: { name: file.name, url } };
});
function onError(reason) {
  error.value = reason === 'size' ? '文件超过 1 MB' : reason === 'exceed' ? '最多选择 3 张图片' : String(reason);
}
onBeforeUnmount(() => previewUrls.forEach((url) => URL.revokeObjectURL(url)));
</script>

示例结果组件与模拟接口代码见 辅助文件。独立组件属性与 Form 列配置的区别见 基础组件使用约定。

属性

属性	类型	默认值	说明
action	string	空字符串	上传接口
data / headers	object	{}	附加表单参数与请求头
propsHttp	object	name/url/file	响应键及上传字段映射，见下文
props	object	label/value/type	对象模式保存的名称、地址、文件类型键
dataType	string	—	object / string / json 等
listType	string	空字符串	text / picture / picture-card / picture-img
multiple / directory	boolean	false	多文件选择与文件夹选择
showFileList	boolean	true	已上传列表
accept	string/array	空字符串	文件选择器允许的类型
limit	number	—	数量上限
fileSize	number	—	大小上限，单位 KB
fileType	string	—	无后缀时指定 img/audio/video
fileText / loadText	string	— / Loading...	选择按钮与等待文案
dragFile / drag	boolean	false	文件拖入上传 / 文件排序，功能不同
httpRequest	function	—	(config, column)，接管默认流程
paramsList	array	[]	对象模式额外字段映射 [{ label: 保存键, value: 响应键 }]

响应映射

propsHttp.res 从 axios 响应体开始取值；例如响应体是 { data: { url, name } }，配置 { res: 'data', url: 'url', name: 'name' }。默认上传字段名为 file，可用 propsHttp.fileName 修改；propsHttp.home 用于补齐相对地址前缀。

上传回调

这些是函数 props。独立组件写 :upload-before="before"，Form 可配置顶层函数 prop，或在 upload 列上写 uploadBefore；列上的函数优先。

属性	签名	处理方式
uploadBefore / upload-before	(file, done, stop, column)	done(newFile?) 继续，stop(error?) 终止
uploadAfter / upload-after	(res, done, stop, column)	done(data?) 保存结果，stop(error?) 放弃结果
uploadDelete / upload-delete	(file, column) => Promise	resolve 删除，reject 阻止；避免返回普通 boolean
uploadPreview / upload-preview	(file, column, done)	done() 调用内置预览
uploadError / upload-error	(error, column)	接收失败，大小/数量限制也会通知
uploadExceed / upload-exceed	(limit, files, fileList, column)	超过数量
uploadSized / upload-sized	(fileSize, file, fileList, column)	超过大小，属性名有 d

before/after 的停止回调不是 loading 布尔值。异步处理需要在每条分支调用相应的 done 或 stop，否则操作无法完成。before 可传新的 File 改名；after 的 res 已按 propsHttp.res 解析。

设置 httpRequest 后，组件直接调用 httpRequest(config, column) 并退出默认流程，不再自动执行大小校验、before/after 或写入绑定值；自定义逻辑应自行完成请求、状态、校验及数据同步。

更多场景见 Upload 表单。