渐进式文件上传:用户体验与技术指南

渐进式文件上传在每个阶段都给用户即时、可信的反馈：文件拖入的那一刻，显示选中确认；上传过程中，平滑的进度条配上合理的剩余时间估计；失败时，提供具体的重试选项；完成后，清晰的成功状态加上下一步操作。技术成分包括：通过 HTML5 DataTransfer API 实现拖放，分块上传与断点续传，ReadableStream 的 fetch 流式传输用于字节精度进度，以及通过 IndexedDB 在标签页刷新后仍能存活的状态管理。做对了，用户上传5GB文件时不会疑惑应用是否卡死了。

"渐进式"在这里真正意味着什么

渐进式在此有两层含义。其一：渐进增强——上传在2012年的浏览器上作为普通 <input type="file"> POST 也能工作，在 JavaScript 可用时再获得拖放、分块和重试功能。其二：渐进披露——UI 仅在需要时才揭示复杂性——上传时显示百分比，失败时才显示重试详情。两层含义指向同一原则：用户不应遇到死胡同，也不应在没有信息的情况下等待。

需要避免的失败模式是"无底洞转圈"——一个通用的加载动画，没有任何进度、剩余时间或是否出错的提示。用户会取消他们不信任的上传。

不与浏览器作对的拖放

HTML5 拖放 API 以漏洞闻名。几条让它可用的规则：

const dropzone = document.querySelector('.dropzone');
dropzone.addEventListener('dragover', (e) => {
  e.preventDefault();
  dropzone.classList.add('dragging');
});
dropzone.addEventListener('dragleave', () => {
  dropzone.classList.remove('dragging');
});
dropzone.addEventListener('drop', (e) => {
  e.preventDefault();
  dropzone.classList.remove('dragging');
  handleFiles([...e.dataTransfer.files]);
});

在 dragover 上调用 preventDefault，否则放置目标不会接受拖放。如果需要通过 webkitGetAsEntry() 接受文件夹，使用 e.dataTransfer.items 而非 files——这是在 Chrome 和 Firefox 上递归捕获目录内容的唯一方式。

同样让回退方案可用：一个包裹样式化 <input type="file" multiple> 的可见 <label> 对100%的用户有效，包括键盘和屏幕阅读器导航。

展示用户相信的进度

进度条跳跃的原因有三：分块大小不均、TCP 慢启动，以及网络栈中的缓冲。用2秒滑动平均平滑：

const samples = []; // [{ time, bytes }]
function recordSample(bytes) {
  const now = performance.now();
  samples.push({ time: now, bytes });
  while (samples.length > 1 && now - samples[0].time > 2000) samples.shift();
}
function throughput() {
  if (samples.length < 2) return 0;
  const delta = samples[samples.length - 1];
  const base = samples[0];
  return (delta.bytes - base.bytes) / ((delta.time - base.time) / 1000);
}

用 (totalBytes - uploadedBytes) / throughput() 计算剩余时间，显示时至少钳制到5秒，并用人类可读的格式表达："约2分钟"而非"124.3秒"。同时显示百分比和字节数（"340 MB / 2.1 GB"）——用户在感觉不对时会交叉核对这两个数字。

有可操作恢复方案的错误状态

通用的"上传失败"消息会破坏信任。将失败分为五类，分别清晰展示：

网络断开（离线事件、TCP 重置）："正在重连..."并自动重试
服务器 5xx："服务器错误，5秒后重试"配手动重试按钮
服务器 4xx（413 文件过大、415 格式不对）："文件被拒绝：太大"配文件替换入口
认证过期（401、403）："会话已过期，请重新登录以继续"
客户端崩溃（JS 错误、浏览器关闭标签页）：重新加载时从 IndexedDB 恢复

将消息与解决该问题的唯一行动配对。如果用户离线，通过 navigator.onLine 和 online 事件监控并展示在线/离线状态。

用 Fetch 流追踪字节

XMLHttpRequest.upload.onprogress 是追踪上传进度的传统方式，但在 HTTP/3 上不稳定，会漏掉在发送缓冲区中排队的字节。现代方式使用 ReadableStream 在字节产生时计数：

function trackedStream(blob, onBytes) {
  let sent = 0;
  return new ReadableStream({
    async pull(controller) {
      const reader = blob.stream().getReader();
      while (true) {
        const { done, value } = await reader.read();
        if (done) { controller.close(); return; }
        sent += value.byteLength;
        onBytes(sent);
        controller.enqueue(value);
      }
    }
  });
}

将流作为 body 传给 fetch，使用 duplex: 'half'。Safari 对请求流的支持在17.4版本落地；此前回退到 XMLHttpRequest。这提供了与实际交给网络栈的字节相关联的毫秒级精度进度。

暂停、恢复和取消

任何需要超过一分钟的上传，用户都期望有暂停按钮。使用分块上传时，暂停就是"停止分发新分块"，恢复则从工作队列留下的地方继续。取消使用 AbortController：

const ctrl = new AbortController();
cancelButton.onclick = () => ctrl.abort();
await fetch(url, { method: 'PUT', body: blob, signal: ctrl.signal });

中止时清理：在服务器端 DELETE 上传会话（避免存储泄漏），清除 IndexedDB 条目，返回初始状态。暂停应保留状态；取消应销毁状态。在 UI 中让这个区别可见。

在标签页刷新后存活

每次成功分块后持久化上传状态：

await idb.put('uploads', {
  sessionId, fileFingerprint, fileName, fileSize,
  completedChunks: [...done], updatedAt: Date.now()
}, sessionId);

指纹是文件前1MB加大小和 lastModified 的 SHA-256——足够在用户刷新后重新选取文件时重新识别。页面加载时，检查 IndexedDB 中一小时内的会话，并提供恢复："你有一个12分钟前的上传任务正在进行中。是否恢复？"不要未经同意自动恢复——用户有时正是为了取消而刷新。

无障碍和键盘友好的交互

只响应鼠标拖拽的放置区，屏幕阅读器用户和键盘用户无法使用。添加：

放置区上的 role="button" 和 tabindex="0"
Enter/Space 键处理器，点击文件输入
进度区域上的 aria-live="polite"，让屏幕阅读器播报里程碑
可见的焦点样式，不只是悬停样式
清晰的标签——"上传文件"胜过"浏览"，胜过一个裸图标

键盘测试很快：拔掉鼠标10分钟，尝试完成一次上传。如果你做不到，你的部分用户也做不到。

HexaTransfer 的上传器正是使用这种渐进式模式——纯表单回退、拖放增强、fetch 流式传输、IndexedDB 支持的断点续传，以及具体的错误恢复。免费试用 hexatransfer.com——无需注册，单次最大10GB。

用户真正注意到的细节

将平淡的上传器与出色上传器区分开来的打磨，存在于小的瞬间：拖放动画确认文件已被捕获，进度条平滑填充而非跳跃，剩余时间估计随时间变得更准确而非乱跳，具体的错误信息告诉你下一步该做什么，意外刷新后的恢复提示，完成状态足够持久以便复制分享链接，以及取消操作立即真正停止上传。这些每个都是几行代码。全部交付，你的上传器的体验就比默认的 <input type="file"> 高出一个数量级。