JS怎么实现文件上传进度条?监听XMLHttpRequest上传进度的完整示例
深入讲解在原生JavaScript中利用XMLHttpRequest与xhr.upload.onprogress事件监听文件上传进度的方法。包含完整HTML与JS代码示例、数据计算公式、核心运行机制与常见卡死陷阱排查。
XMLHttpRequest 对象的 upload 属性监听 progress 事件。通过读取该事件所携带的已发送字节数(loaded)与总字节数(total),动态计算百分比并实时同步到 DOM 界面。本文将提供可直接运行的前端完整代码,并详解核心事件机制、进度计算逻辑及常见异常排查。
一、核心原理:为什么必须使用 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)的数据流传输。
xhr.upload 上,包括 loadstart、progress、load、error 和 abort;而针对服务器最终业务响应状态的判断,则在 xhr 实例自身(xhr.onload)上进行。
二、完整实现步骤与时序规范
实现文件上传进度条不仅需要编写监听函数,还必须遵循严格的代码执行顺序。若时序颠倒,可能导致进度事件在监听器挂载前就已触发完毕,从而导致界面出现假死或跳变。
标准的操作步骤可清晰拆分为五个阶段:
- 准备文件数据:通过
<input type="file">元素获取用户选中的File对象,使用new FormData()构造标准的多部分表单数据(multipart/form-data)。 - 实例化请求对象:执行
const xhr = new XMLHttpRequest();,获得请求通道与对应的xhr.upload接口。 - 提前挂载事件监听:在调用
xhr.send()之前,为xhr.upload绑定progress、load、error事件,并为xhr绑定load(业务响应)事件。 - 建立连接并发送数据:调用
xhr.open('POST', url)指定请求目标,再调用xhr.send(formData)启动传输。 - 接收最终响应:等待
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 对象。深入了解其属性构成有助于编写健壮的容错逻辑。
| 属性名称 | 数据类型 | 含义解释与注意事项 |
|---|---|---|
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% 破损样式。
五、高频踩坑点与深度排查
在真实业务场景中,很多开发者按照标准示例编码后,仍然会遇到各种看似诡异的现象。以下是最典型的四个问题及其底层原因。
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()主动取消的功能。
怎么正确清除JavaScript定时器防止内存泄漏
2026-11-19 15:14:21
JavaScript if判断中常见的赋值误写错误
2026-11-19 12:26:41
JavaScript计算器逻辑详解:怎么处理连续运算符与状态管理
2026-11-19 12:24:14
原生JavaScript插件开发:IIFE封装与API设计指南
2026-11-19 09:58:10
JS添加数组元素时怎么不修改原数组
2026-11-18 23:47:34








