# 7.5 前端文件组件

:::tip 概述
前端文件能力集中在 `ui/src/components` 的几个公共组件：Upload（上传）、Editor（富文本）、Cropper（裁剪）、importFile（导入）。它们与后端两段式上传契约严格对齐。
:::

## 组件清单

| 组件 | 职责 |
|---|---|
| Upload | 文件/图片上传（对接两段式：先 temp 拿 URL，随表单提交） |
| Editor | 富文本编辑器（TinyMCE / vue-quill 双引擎可选） |
| Cropper / cropperjs | 图片裁剪（头像场景：裁剪后上传） |
| importFile | 导入文件选择 + 上传交互 |
| Excel | 前端侧 Excel 解析/生成 |

## Upload 与两段式契约

```text
用户选择文件 → 调上传接口（multipart，dto 经 UnmarshalBody 解析）
            → 后端 SaveTemp → 返回 temp URL
表单提交     → 表单字段携带该 URL
保存记录     → 后端 saveTransform 转正（FileFields 声明）
```

前端**只持有 URL**，不关心物理路径——转正时机与目录由后端声明决定。

## Editor 与占位符契约

- 编辑器产出标准 HTML，正文内本站图片经上传拿到相对路径
- 保存后由后端 ContentFields 占位符化；回显时读侧已还原为完整 URL
- 前端无需实现占位符逻辑（契约在后端唯一出口处理）

## Cropper 典型流

```text
选择图片 → Cropper 裁剪 → 裁剪结果 Blob → Upload 上传 → 表单存 URL
```

个人中心头像即此流程（setting/profile）。

## 使用规约

- 业务页面不直接写 axios 上传，一律用公共组件
- 组件不耦合具体模块（模块私有组件放 views 下 components/）
- 扩展名/大小限制以服务端配置为准，前端提示仅是体验层

## 相关

- [9.10 数据录入组件](/zh/frontend/form-components.html)
- [7.1 文件上传全流程](/zh/tools/upload.html)