72 lines
3.2 KiB
Markdown
72 lines
3.2 KiB
Markdown
# 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 |
|