文件上传与管理系统
目的
文件上传与管理系统提供了一种方法论，用于设计从用户设备到服务器的完整文件传输体验。它确保该过程透明、可恢复且可访问。该系统定义了上传触发器（拖放区域）的交互状态、上传队列的空间节奏以及维持用户在高延迟操作中信心所需的反馈循环（进度、成功和错误）。
使用场景
- 内容管理系统： 设计媒体库和资源上传器。
- SaaS 应用： 实现文档管理、CSV 导入或用户资料附件。
- 项目管理工具： 在任务或评论中结构化文件附件。
- 创意工具： 设计用于照片、视频或设计文件的高容量上传器。
- 云存储界面： 管理复杂的文件夹和文件上传操作。
何时不使用
- 小型文本附件： 如果“文件”只是很短的文本片段，请使用标准文本区域或
copy-to-clipboard-implementation。 - 系统自动传输： 用户不触发或监控上传的情况（例如，后台遥测）。
- 单输入头像照片： 虽然本系统适用，但对于低复杂度的单张图片更新，来自
user-avatar-system的简单“头像”触发器可能更合适。 - 静态资源： 对于作为站点代码一部分的资源（例如，图标、主题图片），这些资源通过开发人员工作流程进行管理。
输入
- 文件类型和大小限制： 允许什么格式（PDF, JPG, PNG）以及最大大小是多少？
- 数量预期： 用户是一次上传一个文件还是批量上传 50 个以上？
- 上传上下文： 这是一个独立任务（例如，“导入数据”）还是一个辅助操作（例如，“附加到消息”）？
- 元数据需求： 文件在上传过程中是否需要标题、描述或标签？
- 系统令牌： 来自父级设计系统的间距、颜色和排版比例。
输出
- 拖放区域结构规范： 上传触发器的视觉定义（空闲、悬停、活跃和禁用状态）。
- 队列管理蓝图： “待处理”、“上传中”和“已完成”列表项的空间组织。
- 进度与反馈矩阵： 进度条、百分比指示器和成功/错误状态的视觉处理。
- 操作层级： 文件列表内“取消”、“重试”、“删除”和“编辑”操作的规则。
工作流程
1. 设计上传触发器（拖放区域）
建立清晰的交互邀请：
- 空闲状态： 使用虚线或实线边框，配以图标（通常是云上传或回形针）和清晰的指示（例如，“拖放或点击上传”）。
- 拖拽悬停状态： 更改背景颜色或边框样式，以提供该区域已准备好接收文件的即时反馈。
- 移动端备选方案： 确保拖放区域仍然是一个大的、可点击的按钮（根据 WCAG 2.2 SC 2.5.8 最小 24x24px，建议 44x44px），用于打开原生系统文件选择器。
2. 建立上传队列
管理多个文件而不使界面混乱：
- 即时反馈： 一旦选择了文件，立即将其添加到触发器下方或内部的列表中。
- 文件结构： 每个列表项应包括：
- 缩略图/图标： 帮助用户识别文件类型或内容。
- 文件名和大小： 确认选择了正确的文件。
- 进度指示器： 显示上传状态的条或圈。
- 操作： 取消正在进行的上传或移除已完成上传的方法。
3. 提供细粒度的状态反馈
使用 step-progress-system 和 interactive-state-system 处理文件状态：
- 上传中： 显示进度条，对于长时间的上传，显示百分比或“已上传 X / Y MB”。
- 成功： 使用语义化的“成功”颜色（绿色）和勾选图标。提供“查看”或“链接”操作。
- 错误： 使用语义化的“错误”颜色（红色）。提供明确的原因（例如，“文件太大”）和“重试”按钮。
4. 设计文件管理（上传后）
定义用户如何与其上传的资源交互：
- 编辑元数据： 如果需要标题或描述，提供行内编辑或“设置”弹窗。
- 删除： 使用“垃圾桶”图标并附带确认步骤来执行破坏性操作。
- 网格视图与列表视图： 对于媒体密集型上传，提供缩略图的网格视图；对于文档密集型上传，使用列表视图以获得元数据密度。
5. 规划响应式堆叠
- 紧凑队列： 在移动端，折叠元数据（如文件大小）并优先显示文件名和进度条。
- 全屏焦点： 对于复杂的上传器（例如，带有映射的 CSV 导入器），使用全屏覆盖层以排除干扰。
决策规则
- “即时条目”规则： 文件在被拖放/选择的瞬间必须立即出现在 UI 中，即使实际的服务器请求尚未开始。
- 进度可见性： 对于任何上传时间超过 1 秒的文件，使用进度条。对于非常快的上传，直接过渡到“成功”状态。
- 批量操作： 如果用户可以上传 5 个以上文件，提供“全部清除”或“全部上传”操作来集体管理队列。
- 冲突管理： 定义如果存在同名文件时会发生什么（例如，“保留两者”、“替换”、“跳过”）。
- 空状态： 如果媒体库为空，使用
empty-state-system将“上传”按钮作为主要 CTA。
约束条件
- 可访问性：
- 拖放区域必须可聚焦，并可通过
Space或Enter键操作。 - 使用
aria-live="polite"向屏幕阅读器宣布上传进度和完成（避免用每一个百分比点进行轰炸）。 - 文件输入必须有一个隐藏但可访问的
<label>。 - 确保焦点永远不会被卡在拖放区域或进度列表后面（WCAG 2.4.11 焦点不被遮挡）——粘性页眉或提示不得覆盖聚焦的元素。
- 取消/重试/删除操作的触摸目标必须至少达到 24x24px（WCAG 2.2 SC 2.5.8）；主操作建议为 44x44px。
- 拖放区域必须可聚焦，并可通过
- 响应式： 拖放区域应是流式的，并且永远不会引起水平溢出。
- 对比度： 进度条和错误消息必须满足 WCAG AA（4.5:1）对比度比。
常见失败模式
- “静默失败”： 上传失败，但 UI 未提供任何反馈，导致用户无限期等待。
- 进度条消失： 在上传实际完成之前，进度条就消失了，导致“后期焦虑”。
- 拖放区域过小： 创建了一个难以用鼠标或拇指点击的微小目标。
- 缺少“取消”： 不允许用户停止大型意外上传。
- 模糊的错误信息： 显示“错误 500”而不是“服务器当前正忙，请稍后再试”。
验证标准
- 拖放区域具有明显的空闲、悬停和拖拽悬停状态。
- 队列中的每个文件都显示名称、大小和进度。
- 成功和错误状态通过颜色和图标指示。
- 用户可以从队列中取消或移除文件。
- 使用 ARIA live 区域进行状态更新。
- 布局响应式，并能优雅地处理长文件名。
- 所有交互元素满足 WCAG 2.2 24x24px 触摸目标最小值（建议 44x44px）。