上传组件

上传组件提供了文件上传功能，支持图片、文档、视频、音频等多种文件类型的上传。组件提供了丰富的配置选项，支持多文件上传、文件预览、上传进度监控等功能，有助于实现灵活的文件管理场景。

基础使用

设置上传成功回调

在上传组件的 onSuccess 回调中，必须将上传成功后的 URL 赋值给 file.url，否则表单将无法获取文件数据：

function onSuccess(res, file, fileList) {
    // 将上传后的URL赋值给file.url
    file.url = res.data.url;
}

这样可以确保表单提交时能够正确获取上传的文件信息。

设置请求头

文件上传时将触发表单的 beforeFetch 事件，可在该事件回调中修改请求头(headers)配置，例如添加认证token：

function beforeFetch(config, data) {
    // 从外部数据获取全局 token
    const token = data.api.getData('globalToken');
    if (!config.headers) {
        config.headers = {};
    }
    config.headers.token = token;
}

保存更多数据

如果期望上传组件的 value 类型为 object[]，需要将上传的结果数据赋值给 file.value：

function onSuccess(res, file, fileList) {
    file.url = res.data.url;
    file.name = res.data.name;
    file.value = res.data;  // 保存完整的返回数据
}

配置项

上传组件提供了丰富的配置选项，您可以通过在设计器中配置属性来自定义上传组件的行为。

属性名	类型	默认值	必需	说明
disabled	Boolean	-	否	是否禁用
listType	String	picture-card	否	文件列表类型（text/picture/picture-card）
multiple	Boolean	-	否	是否支持多文件上传
name	String	-	否	上传的文件字段名
accept	String	-	否	接受上传的文件类型
action	String	/	否	上传的地址
beforeUpload	Function	-	否	上传文件之前的钩子
beforeRemove	Function	-	否	删除文件之前的钩子
onSuccess	Function	-	否	文件上传成功时的钩子
headers	Object	-	否	设置上传请求头
data	Object	-	否	上传时附带的额外参数
withCredentials	Boolean	-	否	支持发送 cookie 凭证信息
autoUpload	Boolean	true	否	是否自动上传
limit	Number	-	否	最大允许上传个数

重要说明：

• listType：设置上传文件列表的展示方式，picture-card 适用于图片上传
• onSuccess：必须在此回调中设置 file.url，否则表单无法获取文件数据
• accept：可以设置为文件类型（如 image/*、.pdf 等）来限制上传文件类型
• action：上传接口地址，可以是完整的 URL 或相对路径

事件

上传组件提供了丰富的事件，方便您监听上传状态变化并执行相应的处理。

事件名	参数	说明
change	file, fileList	文件状态改变时的钩子
remove	file, fileList	文件列表移除文件时的钩子
preview	file	点击文件列表中已上传的文件时的钩子
error	error, file, fileList	上传失败时的钩子
progress	event, file, fileList	上传进度时的钩子
exceed	files, fileList	文件超出个数限制时的钩子

事件使用示例

监听文件变化：

function handleChange(file, fileList) {
    console.log('文件变化:', file);
    console.log('文件列表:', fileList);
}

监听文件移除：

function handleRemove(file, fileList) {
    console.log('删除文件:', file.name);
    // 可以在这里执行删除后的逻辑
}

监听上传错误：

function handleError(error, file, fileList) {
    console.error('上传失败:', error);
    // 显示错误提示
}

监听上传进度：

function handleProgress(event, file, fileList) {
    const percent = (event.loaded / event.total) * 100;
    console.log('上传进度:', Math.round(percent) + '%');
}

方法

上传组件内部提供了多种方法，用于处理文件上传的各种操作。

方法名	参数	说明	返回值
clearFiles	-	清空已上传的文件列表	-
abort	file	取消上传	-
submit	-	手动上传文件列表	-

方法使用示例

清空文件列表：

function clearUpload($inject) {
    const uploadInstance = $inject.api.el('ref_F2vulxvqc841dac');
    uploadInstance.clearFiles();
}

取消上传：

function abortUpload($inject) {
    const uploadInstance = $inject.api.el('ref_F2vulxvqc841dac');
    uploadInstance.abort(file);
}

注意事项

1. 必须设置 file.url：在 onSuccess 回调中必须设置 file.url = res.data.url，否则表单提交时无法获取文件信息。

2. beforeFetch 事件：如果需要添加上传请求头（如认证 token），应该在表单的 beforeFetch 事件中设置，而不是在组件的 headers 属性中设置。

3. 不同 UI 框架的配置差异：element-plus 和 ant-design-vue 在上传组件的配置上存在差异，请根据使用的 UI 框架查看对应文档：

   • Element Plus：Upload 上传组件
   • Ant Design Vue：Upload 上传组件