怎么在JS中监控图片上传进度并显示进度条
详细讲解在原生JavaScript中如何通过XMLHttpRequest的upload.onprogress事件精确监控图片上传进度,并实时更新进度条与百分比显示,涵盖完整代码、核心原理、关键状态处理与常见问题排查。
假设用户在网页管理后台选择了一张 15MB 的高清商品海报进行上传。点击“确定”按钮后,如果页面没有任何状态提示,在漫长的数据发送阶段,界面看起来就像彻底卡死了一样。不知情的用户极易误判为操作失败,进而反复点击提交或直接刷新页面,不仅严重破坏了交互体验,还可能导致服务端接收到大量重复请求。
在 JavaScript 中解决这个问题的核心答案非常明确:使用 XMLHttpRequest 实例的 upload.onprogress 事件监听数据上行传输流。在事件回调中,通过读取 event.loaded(已发送字节)和 event.total(总字节),计算出当前完成的百分比,并将该数值实时映射到页面的进度条组件中。本文将从监听机制、代码实现、关键状态控制及避坑事项,系统讲解如何完整落地这一功能。
一、为什么原生 fetch() 无法直接监听上传进度
许多开发者在接触现代前端时,习惯于使用原生的 fetch() API 来发起异步网络请求。但当面对“监控图片上传进度”这一需求时,fetch() 却往往无法直接胜任。
在底层机制上,fetch() 的设计重点在于基于 Promise 的异步流式控制,它天然支持方便地监听响应数据流的读取进度(即服务端向客户端下发的 Response 流),但对于请求体(Request Body)的上传流,标准虽然定义了可写流方案(fetch duplex streams),但在跨浏览器兼容性、协议限制以及实际开发复杂度上门槛极高,浏览器普遍没有为 fetch() 提供类似 progress 事件的原生事件接口。
相比之下,历史悠久的 XMLHttpRequest(XHR)拥有极其完善且可靠的事件规范。XHR 实例独立提供了一个专门针对上行数据的 xhr.upload 对象(即 XMLHttpRequestUpload)。只要客户端在向服务端推送数据包,该对象就会持续高频触发 progress 事件,这正是目前浏览器端监控文件上传进度最稳固的标准途径。
二、监控上传进度的核心操作步骤
实现图片上传进度监控的过程可以清晰划分为五个连续步骤。每一个步骤承担独立职责,前后数据严谨串联:
- 获取并检验待上传的图片文件:通过
<input type="file">元素获取用户所选文件列表中的File对象,预先对文件格式(如 JPEG、PNG、WebP)及尺寸上限进行校验。 - 使用 FormData 封装二进制载荷:实例化
FormData,使用append()将文件对象打包,浏览器会自动设置正确的multipart/form-data边界标识与请求头。 - 创建并配置 XMLHttpRequest 实例:调用
new XMLHttpRequest(),配置 HTTP 方法与目标接口地址。 - 绑定上传进度与状态事件监听器:在调用
send()发送数据之前,必须先完成对xhr.upload.onprogress的监听绑定,同时注册onload、onerror和ontimeout等生命周期事件。 - 解析事件数据并实时驱动 UI 渲染:在每次
onprogress触发时,检查event.lengthComputable,计算出百分比并刷新页面进度条与文字状态。
三、完整可运行代码实现
下面是一份完整的、可以直接运行的原生 HTML、CSS 与 JavaScript 示例。代码无需安装任何外部第三方依赖,通过结构化的 UI 反馈向用户直观展示图片上传阶段的每一个细节。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>图片上传进度演示</title>
<style>
.upload-box {
max-width: 480px;
margin: 40px auto;
padding: 24px;
border: 1px solid #dcdfe6;
border-radius: 8px;
font-family: sans-serif;
}
.progress-container {
margin-top: 20px;
display: none;
}
.progress-track {
width: 100%;
height: 12px;
background-color: #ebeef5;
border-radius: 6px;
overflow: hidden;
}
.progress-bar {
width: 0%;
height: 100%;
background-color: #409eff;
transition: width 0.15s ease-out;
}
.status-text {
margin-top: 8px;
font-size: 13px;
color: #606266;
display: flex;
justify-content: space-between;
}
.btn-submit {
margin-top: 15px;
padding: 8px 18px;
background: #409eff;
color: #fff;
border: none;
border-radius: 4px;
cursor: pointer;
}
.btn-submit:disabled {
background: #a0cfff;
cursor: not-allowed;
}
</style>
</head>
<body>
<div class="upload-box">
<h3>上传图片并查看实时进度</h3>
<input type="file" id="fileInput" accept="image/*" />
<br />
<button id="uploadBtn" class="btn-submit">开始上传</button>
<div id="progressContainer" class="progress-container">
<div class="progress-track">
<div id="progressBar" class="progress-bar"></div>
</div>
<div class="status-text">
<span id="progressPercent">0%</span>
<span id="progressDetails">0 B / 0 B</span>
</div>
</div>
</div>
<script>
const fileInput = document.getElementById('fileInput');
const uploadBtn = document.getElementById('uploadBtn');
const progressContainer = document.getElementById('progressContainer');
const progressBar = document.getElementById('progressBar');
const progressPercent = document.getElementById('progressPercent');
const progressDetails = document.getElementById('progressDetails');
uploadBtn.addEventListener('click', () => {
const file = fileInput.files[0];
if (!file) {
alert('请先选择要上传的图片!');
return;
}
// 1. 打包文件为表单数据
const formData = new FormData();
formData.append('image', file);
// 2. 创建 XMLHttpRequest 实例
const xhr = new XMLHttpRequest();
// 显示进度条容器并重置初始状态
progressContainer.style.display = 'block';
progressBar.style.width = '0%';
progressPercent.textContent = '0%';
progressDetails.textContent = '准备中...';
uploadBtn.disabled = true;
// 3. 核心:监听上传进度事件
xhr.upload.onprogress = function (event) {
if (event.lengthComputable) {
const loaded = event.loaded;
const total = event.total;
const percent = Math.round((loaded / total) * 100);
// 刷新进度条视觉与文案
progressBar.style.width = percent + '%';
progressPercent.textContent = percent + '%';
progressDetails.textContent = formatBytes(loaded) + ' / ' + formatBytes(total);
}
};
// 4. 监听上传完成(此时仅代表客户端发送完毕)
xhr.onload = function () {
if (xhr.status >= 200 && xhr.status < 300) {
progressBar.style.backgroundColor = '#67c23a'; // 成功绿
progressPercent.textContent = '上传成功!';
} else {
progressBar.style.backgroundColor = '#f56c6c'; // 错误红
progressPercent.textContent = '上传失败 (HTTP ' + xhr.status + ')';
}
uploadBtn.disabled = false;
};
// 5. 异常与中断监听
xhr.onerror = function () {
progressBar.style.backgroundColor = '#f56c6c';
progressPercent.textContent = '网络错误,上传失败';
uploadBtn.disabled = false;
};
// 6. 发起 POST 请求
xhr.open('POST', '/api/upload-image', true);
xhr.send(formData);
});
// 辅助工具:将字节数值格式化为可读字符串(KB/MB)
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];
}
</script>
</body>
</html>
四、ProgressEvent 的计算逻辑与状态机流转
为了让进度条运行得平滑、准确,必须透彻理解 onprogress 回调中的事件参数 ProgressEvent。
该事件对象携带两个最关键的数值属性:
event.loaded:截至当前触发时,客户端已经通过底层 TCP 套接字发送给服务器的字节总数。event.total:本次请求体所包含的预计总字节数(通常根据 HTTP 协议中的Content-Length报头计算得出)。
在进行数学运算前,必须先判断布尔值 event.lengthComputable。当且仅当该属性为 true 时,event.total 才具有实际数学意义;若为 false,说明网络层无法提前知晓载荷总大小(例如采用了 Chunked 分块传输),此时不应强行除以 0,而应当在界面显示“加载中”动画或字节递增计数。
五、基于 Axios 库的工程化写法
在现代 Vue 或 React 项目中,如果团队已经引入了网络库 Axios,则无需手动编写原生的 XMLHttpRequest 样本代码。Axios 在底层正是对 XHR 的封装,并优雅地暴露了 onUploadProgress 配置属性。
import axios from 'axios';
async function uploadImage(file) {
const formData = new FormData();
formData.append('image', file);
try {
const response = await axios.post('/api/upload-image', formData, {
headers: {
'Content-Type': 'multipart/form-data'
},
// 监控上传进度
onUploadProgress: (progressEvent) => {
if (progressEvent.total) {
const percent = Math.round((progressEvent.loaded * 100) / progressEvent.total);
console.log(`当前上传进度: ${percent}%`);
// 此处可调用框架的状态管理更新响应式变量
// setProgress(percent);
}
}
});
console.log('图片上传成功,服务端返回地址:', response.data.url);
} catch (error) {
console.error('上传过程中出现异常:', error);
}
}
注意:在 Axios 中传递 FormData 时,绝大多数现代浏览器无需手动写死 headers['Content-Type'],因为浏览器会自动补齐带 boundary(分界符)的 Content-Type。如果强制手动指定而不带 boundary,反而可能导致后端多部分解析失败。
六、高频陷阱排查与最佳实践总结
在真实业务场景中监控图片上传进度时,开发者往往会遇到以下三个典型陷阱,需对照进行针对性处理:
1. 进度条瞬间冲到 100% 后卡住很久
这是最常见的“假死”错觉。原因在于:upload.onprogress 监控的是客户端向服务端发送网络包的过程。当本地网速较快(如千兆内网或 Wi-Fi 良好)时,几兆的图片可以在半秒内迅速传输完毕,使得进度条瞬间达到 100%。但是,服务端在完全接收到二进制图片后,往往还要执行文件落盘、格式校验、安全病毒扫描、裁剪压缩以及同步上传至对象存储(OSS/S3)等耗时任务。在这期间,客户端依然处于等待 HTTP Response 的挂起状态。
解决方案:当 percent 达到 100% 时,进度条不应直接消失,而应将文字切换为“数据已发送,正在同步云端处理中...”,并显示轻量动画,直至 xhr.onload 收到 HTTP 200 响应后再标记为真正完工。
2. event.lengthComputable 始终为 false
在某些自定义传输流或使用了特殊网关代理的情况下,如果客户端在封装请求时未计算出准确的数据长度,导致底层无法获取 total,此时除法会得到 NaN 或 Infinity。对于图片文件上传,只要规范使用 FormData.append(key, File),浏览器都会自动获取 File.size 并准确设置 lengthComputable。务必保证代码中存在 if (event.lengthComputable) 的分支防守。
3. 跨域请求(CORS)与进度事件异常
当图片直传跨域存储桶(如阿里云 OSS 或腾讯云 COS)时,浏览器在发送真实 POST 之前会发起 OPTIONS 预检请求。如果服务端 CORS 响应头缺少 Access-Control-Allow-Origin 或未允许相关 Method,请求将在预检阶段直接抛出 Network Error,根本不会触发任何 upload.onprogress 事件。因此在排查进度条完全不动作时,应首先查看浏览器 DevTools 网络面板中的预检状态。
JS计算年龄时怎么处理时区和闰年误差
2026-11-19 08:04:22
JS遍历对象数组的常用方法:for、forEach与for...of对比
2026-11-18 21:05:31
JS怎么用正则解析非标准格式字符串为数组
2026-11-18 20:34:01
JS怎么获取对象属性个数:Object.keys().length用法详解
2026-11-18 17:21:11
JS数组转字符串:join()自定义分隔符与toString()默认逗号的区别
2026-11-18 16:43:36








