# 7.5 前端文件组件

:::tip 概述
前端文件能力集中在 components/Upload（上传组件族）与 utils/downloadFile（下载工具），配合两段式上传协议：选择文件即调 /api/upload/uploadFile 拿 temp URL，表单提交随业务接口转正。
:::

## 组件清单（ui/src/components/Upload 等）

| 组件/工具 | 职责 |
|-----------|------|
| Upload | 上传组件族（单图/多图/普通文件形态） |
| Cropper / vue-cropper | 图片裁剪（头像上传场景：裁剪后上传） |
| importFile | 导入文件组件（Excel 导入入口，配合 Excel 组件） |
| utils/downloadFile | 文件下载工具（导出 URL 下载） |
| Editor（TinyMCE/Quill） | 富文本编辑器（内嵌图片上传协作，见 7.3） |

## 上传组件与后端协议的协作

```text
1. 用户选择文件 → 前端 POST /api/upload/uploadFile（multipart，字段 file）
   可带 type=image 走图片规则（魔数嗅探）
2. 后端 SaveTemp 落临时目录 → 返回 {originalName, fileExtension, fileType, fileSize, fileName, filePath, fileUrl}
3. 组件回显 fileUrl（预览）、originalName（文件名）；表单数据持有 fileUrl
4. 表单提交（exampleAdd/articleAdd 等）→ 后端 spec.saveTransform
   → SaveFromTemp 把 temp URL 转正 → 库存相对路径
5. 详情回显 → 基座 GetFileUrl 补域名 → 组件直接展示
```

关键认知：**前端只持有 URL（temp 或正式），永远不关心物理路径**；转正发生在业务表单保存时，不在上传时。

## 头像上传（Cropper 场景）

```text
选择图片 → Cropper 裁剪 → 裁剪结果上传 /api/upload/uploadFile（type=image）
→ 得到 temp URL → 头像组件预览
→ 保存资料（index.updateProfile）→ 后端 SaveFileField(avatar, "user") 转正
```

## 多图字段（article.images）

```text
多图上传 → 每张走 uploadFile → 组件持有 URL 数组 → 表单逗号拼接
→ 后端 MultiFileFields 声明 → SaveFromTempMulti 逐个转正
→ 库存逗号分隔相对路径
```

## 下载工具（utils/downloadFile）

```text
导出接口返回文件 URL → downloadFile 触发浏览器下载
（导出文件在 /upload/temp/...，受 tempExpireDays 清理——及时下载）
```

## 开发对接要点

| 场景 | 要点 |
|------|------|
| 新页面接上传 | 用 Upload 组件 + 表单字段持 URL；后端 spec 声明 FileFields + FileSaveDir |
| 图片类字段 | 上传带 type=image（后端魔数嗅探）；后端注释含"图片"（生成器识别为图片列） |
| 多图 | MultiFileFields + 逗号分隔约定 |
| 富文本内图片 | 走 Editor 的上传通道（temp URL 入正文），保存时 Localize 统一转正 |
| 大小/类型拦截 | 前端可预校验（体验优化）；**真值以后端白名单与 maxSize 为准** |

## 排障

| 症状 | 原因 |
|------|------|
| 上传成功但保存后 404 | 转正失败或 domainUrl 配置错；查库中相对路径与 GetFileUrl |
| 上传被拒 | 扩展名/大小/嗅探——对照 file.* 配置（7.2 上传配置详解） |
| 预览正常发布后失效 | temp 已被 CleanTemp 清理——表单保存（转正）没发生或失败 |
| 多图只保存最后一张 | 前端未逗号拼接或后端未声明 MultiFileFields |