Vue / 系统课时
实现文件上传
实现文件上传
本课完成一个可用于管理后台表单的上传组件流程:上传前拦截非法文件,传输中显示进度,失败后允许重试,成功后回填文件 ID,并在删除时同步清理服务端资源。
学习目标
- 在上传前校验文件类型和大小
- 使用自定义请求上报真实上传进度并处理失败重试
- 将上传结果与表单字段、删除接口保持一致
定义上传状态与接口约定
文件上传不是一次简单赋值,而是“待校验、上传中、成功、失败、删除中”的状态过程。表单通常只保存文件 ID,文件名、访问地址等展示信息由上传接口返回。

示例约定 POST /api/files 返回文件对象,DELETE /api/files/<ID> 成功时返回 204。后端路径可替换,但响应中应有稳定的文件 ID。
实现上传、进度与重试
下面是片段示例,依赖 Vue 3、Element Plus 以及上述文件接口。XMLHttpRequest 用于获取原生上传进度,失败文件会保留在列表中供用户重试。
vue
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { ElMessage } from 'element-plus'
import type {
UploadFile,
UploadInstance,
UploadProgressEvent,
UploadRawFile,
UploadRequestOptions,
UploadUserFile
} from 'element-plus'
interface FileResult {
id: string
name: string
url: string
}
const uploadRef = ref<UploadInstance>()
const fileList = ref<UploadUserFile[]>([])
const failedRaw = ref<UploadRawFile>()
const form = reactive({ attachmentId: '' })
const allowedTypes = new Set([
'image/png',
'image/jpeg',
'application/pdf'
])
const maxSize = 5 * 1024 * 1024
function beforeUpload(file: UploadRawFile): boolean {
if (!allowedTypes.has(file.type)) {
ElMessage.error('仅支持 PNG、JPG 或 PDF')
return false
}
if (file.size > maxSize) {
ElMessage.error('文件不能超过 5 MB')
return false
}
return true
}
function sendByXhr(options: UploadRequestOptions): Promise<FileResult> {
return new Promise((resolve, reject) => {
const xhr = new XMLHttpRequest()
const data = new FormData()
data.append(options.filename, options.file)
xhr.upload.addEventListener('progress', (event) => {
if (!event.lengthComputable) return
const progressEvent = event as UploadProgressEvent
progressEvent.percent = Math.round((event.loaded / event.total) * 100)
options.onProgress(progressEvent)
})
xhr.addEventListener('load', () => {
if (xhr.status < 200 || xhr.status >= 300) {
reject(new Error(`上传失败:HTTP ${xhr.status}`))
return
}
resolve(JSON.parse(xhr.responseText) as FileResult)
})
xhr.addEventListener('error', () => reject(new Error('网络连接失败')))
xhr.open('POST', '/api/files')
xhr.send(data)
})
}
async function uploadRequest(
options: UploadRequestOptions
): Promise<FileResult> {
try {
const result = await sendByXhr(options)
form.attachmentId = result.id
failedRaw.value = undefined
options.onSuccess(result)
return result
} catch (error) {
const uploadError =
error instanceof Error ? error : new Error('上传失败')
failedRaw.value = options.file
options.onError(uploadError)
throw uploadError
}
}
function retryUpload(): void {
const target = fileList.value.find(
(item) => item.raw?.uid === failedRaw.value?.uid
)
if (!target) return
// Element Plus 只会提交 ready 状态的文件
target.status = 'ready'
uploadRef.value?.submit()
}
async function beforeRemove(file: UploadFile): Promise<boolean> {
const result = file.response as FileResult | undefined
if (!result?.id) return true
const response = await fetch(`/api/files/${result.id}`, {
method: 'DELETE'
})
if (!response.ok) {
ElMessage.error('删除失败,文件记录已保留')
return false
}
form.attachmentId = ''
return true
}
</script>
<template>
<el-upload
ref="uploadRef"
v-model:file-list="fileList"
:before-upload="beforeUpload"
:http-request="uploadRequest"
:before-remove="beforeRemove"
:limit="1"
>
<el-button type="primary">选择文件</el-button>
<template #tip>
<div>支持 PNG、JPG、PDF,最大 5 MB</div>
</template>
</el-upload>
<el-button v-if="failedRaw" type="warning" @click="retryUpload">
重试上传
</el-button>
</template>预期结果
text
合法文件上传时,列表进度从 0% 增长到 100%。
成功后 form.attachmentId 被回填为 <ID>。
上传失败时出现“重试上传”按钮;删除成功后 attachmentId 清空。实际返回的文件 ID、进度速度和错误状态码会因接口实现而不同。服务端还应再次校验 MIME、扩展名和大小,不能只信任浏览器结果。
保证删除与表单一致
删除失败时必须返回 false,让 Element Plus 保留列表项;否则页面看似删除成功,服务端却仍有文件。业务表单保存失败时,也要明确采用“保留已上传文件”还是“回滚临时文件”的策略。
生产环境建议先上传为临时文件,提交业务表单后再绑定记录;定时任务清理长期未绑定的临时文件,可避免用户关闭页面后留下孤儿文件。
按自己的节奏,确认真正理解。