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 保留列表项;否则页面看似删除成功,服务端却仍有文件。业务表单保存失败时,也要明确采用“保留已上传文件”还是“回滚临时文件”的策略。

生产环境建议先上传为临时文件,提交业务表单后再绑定记录;定时任务清理长期未绑定的临时文件,可避免用户关闭页面后留下孤儿文件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现文件上传

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通