交互与用户体验 / 系统课时

显示附件上传与解析进度

显示附件上传与解析进度

用户选择文件后,界面需要分别回答两个问题:文件传完了吗,内容可以供 AI 使用了吗?本课用明确的状态、分段进度和可恢复操作,设计拖拽、选择、删除及失败处理,并保证附件始终与当前输入关联。

学习目标

  • 区分上传和解析的状态,并给出可信的进度反馈。
  • 设计附件卡片与输入框的发送、删除及去重规则。
  • 使用可复现的案例验收成功、失败和多文件并行场景。

定义从选择到可用的状态

入口可以是拖拽到输入区,也可以是点击回形针按钮打开系统文件选择器;两者进入同一套状态。拖拽悬停时只高亮合法投放区,放下后先做本地校验,再开始上传。

一份文件的正常路径是“待校验→排队→上传中→服务端已接收→解析中→可用”。校验失败、上传失败、解析失败是不同终态;用户取消则进入“已取消”。上传到 100% 不等于内容可用,必须等服务端确认接收及解析成功后才标记“可用”。

附件上传和解析的状态转换

让进度数字只代表真实进展

上传接口同时报告有效的已传输字节数和请求体总字节数时,可以显示百分比。例如发送 6.8 MB、总量 10 MB 时显示 68%。浏览器报告的请求体总量可能包含表单开销,计算时应使用同一事件来源的两个数;总量未知时只显示状态。传输结束后显示“等待服务端确认”。

解析若只有开始与结束事件,就显示“正在提取内容”及不定进度指示,不编造 80% 等数字。只有服务端提供可靠的完成量与总量时,才可显示“已处理 8/12 页”;图片识别等没有页数的任务继续使用阶段文案。

每张附件卡片独立显示状态,不用一个总进度遮盖慢文件。对于屏幕阅读器,播报“报告.pdf,上传 68%”及状态变化即可,避免每增加 1% 就连续播报。进度条旁保留文字,以免只靠颜色区分成功和失败。

绑定草稿、附件与发送动作

附件卡片放在当前输入框上方,显示文件名、大小、状态和移除入口;文本始终可继续编辑。每个附件绑定当前草稿标识,发送时由草稿关联已解析成功的文件标识,不能仅凭页面上的文件名判断附件是否存在。

本例采用明确的发送规则:有正文或附件且全部未移除附件均处于可用状态时才能发送;上传中、解析中或存在失败卡片时禁用发送,并显示原因。用户可重试失败附件,或移除后仅发送其余内容。提交时冻结这次发送的文本、附件和草稿版本;发送成功后只清理已提交的草稿版本,用户在等待期间的新输入应保留。服务端按用户、当前会话和可用状态验证文件标识。删除输入框附件不会改动已发送的历史消息。

输入框与附件卡片的布局及发送状态

处理限制、重复与移除

以下是一组用于交互原型的产品示例限制,并非所有 AI 服务通用:允许 PDF、DOCX、TXT、PNG、JPG,最多 5 个文件,单文件不超过 20 MB,合计不超过 50 MB。客户端先检查扩展名、类型、大小与数量;服务端按允许的类型、文件签名、大小及数量校验,限制解包和解析资源,并在满足安全检查后才允许引用。客户端传来的类型声明不能作为安全依据。若选择的 PDF 为 24.6 MB,直接提示“超过单文件 20 MB 上限”,不进入上传;其他合规文件仍可继续。

同一草稿再次选择文件时,文件名与大小相同只能用来提示疑似重复,不能据此认定内容完全相同。可用文件内容哈希确认重复后,聚焦已存在的附件卡片而不是再添一张;同名但内容不同的文件允许共存,并通过大小或序号区分。

移除排队中的文件应直接取消任务;上传中的文件应中止传输;已上传或解析中的文件应立即解除草稿引用,并触发服务端取消或清理流程。界面只能确认“已从本次输入移除”,不能在服务端未确认时声称文件已经永久删除。

在草稿层丢弃过期的解析事件

事件同时标识草稿、附件和当前尝试。同一附件重试后分配新的尝试 ID,被移除的附件从草稿记录中删除。示例只处理解析完成事件。

javascript
function acceptParsed(draft, event) {
  if (event.draftId !== draft.id) return false;
  const item = draft.items.get(event.attachmentId);
  if (!item || item.attemptId !== event.attemptId || item.state !== "parsing") {
    return false;
  }
  item.state = "ready";
  item.fileId = event.fileId;
  return true;
}

const draft = {
  id: "draft-1",
  items: new Map([["a", { attemptId: "try-2", state: "parsing" }]]),
};
const event = { draftId: "draft-1", attachmentId: "a", fileId: "file-42" };
console.log(acceptParsed(draft, { ...event, attemptId: "try-1" })); // false
console.log(acceptParsed(draft, { ...event, attemptId: "try-2" })); // true
draft.items.delete("a");
console.log(acceptParsed(draft, { ...event, attemptId: "try-2" })); // false

设计可恢复的失败路径并验收

上传失败时保留文件卡片和已输入文本,展示“重试上传 / 移除”;重新上传必须避免产生重复附件。解析失败时展示“重试解析 / 移除”:只有后端支持复用已上传文件时才能直接重试解析,否则明确提示需要重新上传。一个文件失败不应清掉其他已可用的文件。

验收操作 应看到的结果
拖入 24.6 MB PDF 显示 20 MB 限制,文件不上传
A 上传 68%,B 正在解析 两张卡片分别显示状态,发送禁用
A 上传达到 100%,服务端尚未确认 显示等待确认,不标记可用
在上传中移除 A A 从草稿移除,发送条件重新计算
B 解析失败后移除 保留输入文字及其他可用附件
所有附件可用并提交 消息绑定对应文件标识,成功后清空草稿

验收时还要模拟断网、连续点击重试、同一文件重复拖入,以及上传与移除同时发生。无论响应返回顺序如何,被移除的旧任务都不能重新把卡片变为“可用”;发送也不能携带已取消或解析失败的文件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

显示附件上传与解析进度

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通