JS怎么实现文件上传进度条?监听XMLHttpRequest上传进度的完整示例

作者:拾光

时间:2026-11-19

浏览:164

深入讲解在原生JavaScript中利用XMLHttpRequest与xhr.upload.onprogress事件监听文件上传进度的方法。包含完整HTML与JS代码示例、数据计算公式、核心运行机制与常见卡死陷阱排查。

文章目录
在原生 JavaScript 中实现真实文件上传进度条,核心方案是借助 XMLHttpRequest 对象的 upload 属性监听 progress 事件。通过读取该事件所携带的已发送字节数(loaded)与总字节数(total),动态计算百分比并实时同步到 DOM 界面。本文将提供可直接运行的前端完整代码,并详解核心事件机制、进度计算逻辑及常见异常排查。
JS怎么实现文件上传进度条?监听XMLHttpRequest上传进度的完整示例
图 0:基于 XMLHttpRequestUpload 的文件传输流与实时进度条渲染概览

一、核心原理:为什么必须使用 xhr.upload

很多初学者在尝试给 XMLHttpRequest 绑定进度监听时,容易直接调用 xhr.onprogress = function(event) { ... } 或 xhr.addEventListener('progress', ...),随后发现进度条在上传阶段毫无反应,直到服务端返回响应时才瞬间跳动。

这是因为一个完整的 HTTP 请求包含“上行(发送请求体)”与“下行(接收响应体)”两个方向:

  • xhr 实例自身的 progress 事件:监听的是下行通道,即浏览器从服务器端接收数据(下载/响应正文)的过程。普通文件上传接口返回的通常只是简短的 JSON 状态信息(如 {"code": 200}),体积极小且传输在毫秒级完成,因此直接监听 xhr.onprogress 根本无法观察到文件数据往服务器发送的持续过程。
  • xhr.upload 属性的 progress 事件:监听的是上行通道。xhr.upload 返回的是标准的 XMLHttpRequestUpload 接口对象,专门负责监听浏览器向网络堆栈写入请求体数据(如表单文件、Blob、ArrayBuffer)的数据流传输。
JS怎么实现文件上传进度条?监听XMLHttpRequest上传进度的完整示例
图 1:XMLHttpRequest 上下行通道分工与事件目标对比
关键结论
实现上传进度条时,所有关于“上传过程”的事件监听都必须注册在 xhr.upload 上,包括 loadstart、progress、load、error 和 abort;而针对服务器最终业务响应状态的判断,则在 xhr 实例自身(xhr.onload)上进行。

二、完整实现步骤与时序规范

实现文件上传进度条不仅需要编写监听函数,还必须遵循严格的代码执行顺序。若时序颠倒,可能导致进度事件在监听器挂载前就已触发完毕,从而导致界面出现假死或跳变。

JS怎么实现文件上传进度条?监听XMLHttpRequest上传进度的完整示例
图 2:文件上传进度监听标准实现步骤与生命周期时序

标准的操作步骤可清晰拆分为五个阶段:

  1. 准备文件数据:通过 <input type="file"> 元素获取用户选中的 File 对象,使用 new FormData() 构造标准的多部分表单数据(multipart/form-data)。
  2. 实例化请求对象:执行 const xhr = new XMLHttpRequest();,获得请求通道与对应的 xhr.upload 接口。
  3. 提前挂载事件监听:在调用 xhr.send() 之前,为 xhr.upload 绑定 progress、load、error 事件,并为 xhr 绑定 load(业务响应)事件。
  4. 建立连接并发送数据:调用 xhr.open('POST', url) 指定请求目标,再调用 xhr.send(formData) 启动传输。
  5. 接收最终响应:等待 xhr.onload 触发,校验 HTTP 响应状态码(如 xhr.status === 200),完成业务收尾。

三、可直接运行的完整代码示例

以下代码给出了包含 HTML 界面结构、CSS 进度条样式以及原生 JavaScript 上传与取消逻辑的完整范例。

<!-- HTML 结构 -->
<div class="upload-panel">
  <input type="file" id="fileSelector" />
  <button id="startUploadBtn">开始上传</button>
  <button id="cancelUploadBtn" disabled>取消上传</button>

  <!-- 进度条与状态展示区 -->
  <div class="progress-container" style="margin-top: 16px;">
    <div class="progress-track" style="width: 100%; height: 16px; background: #e2e8f0; border-radius: 8px; overflow: hidden;">
      <div id="progressBar" style="width: 0%; height: 100%; background: #6487a5; transition: width 0.1s linear;"></div>
    </div>
    <div style="display: flex; justify-content: space-between; margin-top: 6px; font-size: 13px; color: #64748b;">
      <span id="progressText">等待上传</span>
      <span id="sizeInfo">0 MB / 0 MB</span>
    </div>
  </div>
  <div id="statusMessage" style="margin-top: 10px; font-size: 14px;"></div>
</div>

<script>
// 获取 DOM 元素
const fileSelector = document.getElementById('fileSelector');
const startUploadBtn = document.getElementById('startUploadBtn');
const cancelUploadBtn = document.getElementById('cancelUploadBtn');
const progressBar = document.getElementById('progressBar');
const progressText = document.getElementById('progressText');
const sizeInfo = document.getElementById('sizeInfo');
const statusMessage = document.getElementById('statusMessage');

let currentXhr = null; // 保持全局引用以便支持取消操作

// 格式化字节大小辅助函数
function formatBytes(bytes) {
  if (bytes === 0) return '0 B';
  const k = 1024;
  const sizes = ['B', 'KB', 'MB', 'GB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return (bytes / Math.pow(k, i)).toFixed(2) + ' ' + sizes[i];
}

// 点击开始上传
startUploadBtn.addEventListener('click', () => {
  const file = fileSelector.files[0];
  if (!file) {
    alert('请先选择要上传的文件!');
    return;
  }

  // 1. 组装表单数据
  const formData = new FormData();
  formData.append('file', file);

  // 2. 实例化 XMLHttpRequest
  currentXhr = new XMLHttpRequest();

  // 重置 UI 状态
  progressBar.style.width = '0%';
  progressBar.style.backgroundColor = '#6487a5';
  progressText.textContent = '0%';
  statusMessage.textContent = '正在连接服务器...';
  statusMessage.style.color = '#334155';
  startUploadBtn.disabled = true;
  cancelUploadBtn.disabled = false;

  // 3. 关键步骤:在 xhr.upload 上监听上传进度 (ProgressEvent)
  currentXhr.upload.addEventListener('progress', (event) => {
    if (event.lengthComputable) {
      // 计算上传百分比
      const percentComplete = (event.loaded / event.total) * 100;
      const formattedPercent = percentComplete.toFixed(1);

      // 更新进度条宽度与文字
      progressBar.style.width = formattedPercent + '%';
      progressText.textContent = formattedPercent + '%';
      sizeInfo.textContent = `${formatBytes(event.loaded)} / ${formatBytes(event.total)}`;

      if (percentComplete >= 100) {
        statusMessage.textContent = '文件已发送完毕,等待服务器写入与响应...';
      } else {
        statusMessage.textContent = '正在上传数据中...';
      }
    } else {
      // 无法计算总长度时的回退提示
      progressText.textContent = '上传中...';
      statusMessage.textContent = '数据流传输中(未知总长度)';
    }
  });

  // 4. 监听请求体发送完毕事件
  currentXhr.upload.addEventListener('load', () => {
    console.log('客户端数据包已全量推入网络管道');
  });

  // 5. 监听服务器处理结果(注意在 currentXhr 自身上监听)
  currentXhr.addEventListener('load', () => {
    startUploadBtn.disabled = false;
    cancelUploadBtn.disabled = true;

    if (currentXhr.status >= 200 && currentXhr.status < 300) {
      progressBar.style.backgroundColor = '#059669'; // 成功变为绿色
      statusMessage.textContent = '上传成功!服务器已确认接收。';
      statusMessage.style.color = '#059669';
    } else {
      progressBar.style.backgroundColor = '#dc2626'; // 失败变红
      statusMessage.textContent = `上传失败:服务器返回状态码 ${currentXhr.status}`;
      statusMessage.style.color = '#dc2626';
    }
  });

  // 6. 监听上传异常与中断
  currentXhr.upload.addEventListener('error', () => {
    startUploadBtn.disabled = false;
    cancelUploadBtn.disabled = true;
    progressBar.style.backgroundColor = '#dc2626';
    statusMessage.textContent = '上传发生网络错误,请检查网络连接或跨域配置!';
    statusMessage.style.color = '#dc2626';
  });

  currentXhr.upload.addEventListener('abort', () => {
    startUploadBtn.disabled = false;
    cancelUploadBtn.disabled = true;
    statusMessage.textContent = '上传已被用户主动取消。';
    statusMessage.style.color = '#c28b68';
  });

  // 7. 打开连接并发出请求
  currentXhr.open('POST', '/api/upload');
  currentXhr.send(formData);
});

// 点击取消上传
cancelUploadBtn.addEventListener('click', () => {
  if (currentXhr) {
    currentXhr.abort(); // 中断连接
    currentXhr = null;
  }
});
</script>

四、ProgressEvent 数据解析与计算细节

当 upload.progress 事件触发时,回调函数接收的参数是一个标准的 ProgressEvent 对象。深入了解其属性构成有助于编写健壮的容错逻辑。

JS怎么实现文件上传进度条?监听XMLHttpRequest上传进度的完整示例
图 3:ProgressEvent 数据结构解析与 UI 双向映射模型
属性名称 数据类型 含义解释与注意事项
event.lengthComputable Boolean 指示底层 HTTP 传输能否准确计算总字节数。当使用分块编码(Chunked Transfer)或请求长度未知时为 false。必须在计算前进行判定。
event.loaded Number (整型字节) 当前已成功推入套接字发送缓冲区的字节总数。数值从 0 持续递增至 total。
event.total Number (整型字节) 本次请求体需要发送的总字节数。包含文件自身大小以及多部分表单(multipart boundary)的元数据开销。

在实际工程中,建议采用 const percent = Math.min(100, Math.round((loaded / total) * 100)) 进行约束,避免极端情况下浮点数精度偏差导致百分比超出 100% 破损样式。

五、高频踩坑点与深度排查

在真实业务场景中,很多开发者按照标准示例编码后,仍然会遇到各种看似诡异的现象。以下是最典型的四个问题及其底层原因。

JS怎么实现文件上传进度条?监听XMLHttpRequest上传进度的完整示例
图 4:全周期状态分支转换与异常处理决策树

1. 为什么进度条到达 100% 后会卡顿几秒甚至很久?

现象:进度条快速走到 100%,但页面迟迟不提示成功,甚至让用户误以为页面卡死。
底层原因:xhr.upload.onprogress 达到的 100% 仅仅代表客户端浏览器的本地网卡已经将整个请求体全部发出。在此之后,数据包仍需经过公网路由器到达服务器,服务器端接收到全部字节后,还需要在磁盘上创建文件、合并分片、进行文件校验(如计算 SHA256)或者上传到后端的对象存储服务中。

规范解法:当 percentComplete >= 100 时,应当在界面上给出明确的状态提示文字(例如“数据已发送完毕,正在保存与校验中...”),避免用户在等待服务端 xhr.onload 响应时产生困惑。

2. 为什么不能在 send() 之后才绑定事件?

JavaScript 采用单线程事件循环机制。当执行 xhr.send(formData) 时,浏览器底层的网络 I/O 线程立即接管数据发送工作。如果上传的是较小的文件(如几百 KB)或者在本地网络/千兆内网环境中传输,数据在微秒级别就可能全部灌入管道。如果在 send() 之后才注册 xhr.upload.onprogress,事件早已经在调用栈前触发完毕,监听器将错过所有进度通知,导致进度条直接空白。

3. 跨域请求(CORS)与预检 OPTIONS 的干扰

如果上传接口与前端页面处于不同域名或端口,浏览器会先发送一次 OPTIONS 预检请求。

  • 服务端必须针对 OPTIONS 请求正确返回包含 Access-Control-Allow-Origin、Access-Control-Allow-Methods 的 204 或 200 响应。
  • 若服务端未放行跨域,浏览器在预检阶段就会抛出网络错误,直接触发 xhr.upload.onerror,上传逻辑根本不会启动。

4. 现代 fetch API 为什么难以完全替代 XHR 上传进度?

虽然现代前端广泛采用 fetch() 取代 XMLHttpRequest 处理普通的 JSON 请求,但在上传进度监听领域,fetch 目前仍存在兼容性壁垒:

  • fetch 的 Request 对象的 body 理论上可以通过 ReadableStream 上传,但大部分主流浏览器对“请求体流式上传”(Request Streams)的实现限制严格(例如强制要求 HTTP/2 双工通信,且兼容性较差)。
  • 而 XMLHttpRequest.upload 从 HTML5 时代起就已标准化,在所有现代浏览器中拥有 100% 的兼容性与高稳定性。因此,在文件上传、断点续传及大文件切片上传场景中,XMLHttpRequest 仍然是行业事实标准。

六、实践总结与快速排查清单

实现稳定、流畅的上传进度体验,只需牢记以下要点:

  • 看准监听对象:必须使用 xhr.upload.addEventListener('progress', fn) 监听上传,在 xhr.addEventListener('load', fn) 验证业务结果。
  • 坚守时序铁律:先 open() 并完成所有事件绑定,最后再执行 send(formData)。
  • 做好状态防御:计算进度前务必检查 event.lengthComputable,在 100% 时展示“文件处理中”过渡文案,并提供通过 xhr.abort() 主动取消的功能。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章