XMLHttpRequest.upload 属性全面解析

词源分解与功能定位

upload 由两部分构成：

• ‌up‌（向上）：表示数据流向

• ‌load‌（加载）：表示数据传输过程

该属性返回一个XMLHttpRequestUpload对象，专门用于监控上传进度和状态，是XHR Level 2规范新增的重要特性

语法结构

基础访问方式：

const uploadObj = xhr.upload;

属性特征：

• 只读属性，返回XMLHttpRequestUpload实例

• 必须在open()之后访问才有意义

• 与XHR共享相同的事件接口

事件类型与参数

1. 支持的事件类型

事件	触发时机	事件对象属性
loadstart	上传开始时触发	loaded, total
progress	数据传输过程中周期性触发	loaded, total, lengthComputable
abort	上传被中止时触发	-
error	上传失败时触发	-
load	上传成功完成时触发	loaded, total
timeout	上传超时时触发	-
loadend	上传结束时触发(无论成功与否)	loaded, total

其中progress事件的event对象包含：

• loaded：已传输字节数

• total：总字节数(如果可计算)

• lengthComputable：布尔值，表示总大小是否可知

属性示例与输出

基础文件上传监控

const xhr = new XMLHttpRequest();
xhr.open('POST', '/upload', true);
xhr.upload.onprogress = function(e) {
  if(e.lengthComputable) {
    const percent = Math.round((e.loaded / e.total) * 100);
    console.log(`上传进度: ${percent}%`);
  }
};
xhr.upload.onload = function() {
  console.log('上传完成');
};
const fileInput = document.getElementById('fileInput');
xhr.send(fileInput.files[0]);
// 输出示例:
// 上传进度: 25%
// 上传进度: 68%
// 上传完成

多事件综合处理

xhr.upload.onloadstart = () => console.log('开始上传');
xhr.upload.onerror = () => console.error('上传失败');
xhr.upload.onabort = () => console.warn('上传已取消');
xhr.upload.ontimeout = () => console.error('上传超时');

应用场景分析

1. 大文件上传进度显示

// 创建进度条UI
const progressBar = document.getElementById('progress');
xhr.upload.onprogress = function(e) {
  if(e.lengthComputable) {
    progressBar.value = (e.loaded / e.total) * 100;
  }
};

2. 断点续传实现

// 记录已上传字节数
let uploadedBytes = 0;
xhr.upload.onprogress = function(e) {
  uploadedBytes = e.loaded;
};
xhr.upload.onerror = function() {
  // 失败时保存已上传量
  localStorage.setItem('resumePoint', uploadedBytes);
};

3. 多文件并行上传控制

// 限制并发上传数
const MAX_UPLOADS = 3;
let activeUploads = 0;
function startUpload(file) {
  if(activeUploads >= MAX_UPLOADS) return false;
  
  const xhr = new XMLHttpRequest();
  xhr.open('POST', '/upload', true);
  activeUploads++;
  
  xhr.upload.onloadend = function() {
    activeUploads--;
    checkQueue();
  };
  
  xhr.send(file);
  return true;
}

注意事项

1. ‌浏览器兼容性‌：

• IE10+支持完整功能

• 移动端浏览器可能有事件触发频率限制

2. ‌性能考量‌：

• 高频progress事件可能影响性能

• 大文件建议适当降低事件处理频率

3. ‌安全限制‌：

• 跨域上传需服务器配置CORS

• 某些浏览器限制上传文件类型

4. ‌与download区别‌：

• upload只监控上行数据

• download监控通过xhr自身事件

综合比较表

特性	upload事件	常规XHR事件	Fetch API
进度监控	精细到字节级	仅整体状态	通过ReadableStream
适用阶段	仅上传阶段	整个请求周期	整个请求周期
事件类型	专有上传事件集	通用HTTP事件	更现代化的事件模型
浏览器支持	IE10+	所有支持XHR的浏览器	现代浏览器
内存效率	中等	中等	较高

最佳实践建议

1. ‌节流优化‌：

let lastUpdate = 0;
xhr.upload.onprogress = function(e) {
  const now = Date.now();
  if(now - lastUpdate > 200) { // 200ms节流
    updateProgress(e);
    lastUpdate = now;
  }
};

1. ‌错误恢复‌：

xhr.upload.onerror = function() {
  if(retryCount++ < 3) {
    setTimeout(retryUpload, 1000);
  }
};

1. ‌用户体验优化‌：

xhr.upload.onloadstart = showSpinner;
xhr.upload.onloadend = hideSpinner;
xhr.upload.onprogress = updateProgressBar;

通过合理利用upload属性，开发者可以实现精细化的上传控制，特别适合大文件传输、实时进度反馈等场景，但需注意浏览器兼容性和性能优化