签入版本

EasyGoAdmin_Gin_NaiveVue/zh/tools/file-components.md

@@ -1,72 +1,51 @@
 # 7.5 前端文件组件
 
 :::tip 概述
-本节介绍前端项目中的文件处理组件，包括上传组件（BasicUpload）和图片预览组件的使用方法。
+前端文件能力集中在 `ui/src/components` 的几个公共组件：Upload（上传）、Editor（富文本）、Cropper（裁剪）、importFile（导入）。它们与后端两段式上传契约严格对齐。
 :::
 
-## Upload 上传组件
+## 组件清单
 
-```vue
-<template>
-  <BasicUpload
-    v-model="formData.avatar"
-    :action="uploadUrl"
-    :maxCount="1"
-  />
-</template>
+| 组件 | 职责 |
+|---|---|
+| Upload | 文件/图片上传（对接两段式：先 temp 拿 URL，随表单提交） |
+| Editor | 富文本编辑器（TinyMCE / vue-quill 双引擎可选） |
+| Cropper / cropperjs | 图片裁剪（头像场景：裁剪后上传） |
+| importFile | 导入文件选择 + 上传交互 |
+| Excel | 前端侧 Excel 解析/生成 |
 
-<script setup>
-import { BasicUpload } from '@/components/Upload';
+## Upload 与两段式契约
 
-const uploadUrl = '/api/upload/uploadFile';
-const formData = ref({ avatar: '' });
-</script>
+```text
+用户选择文件 → 调上传接口（multipart，dto 经 UnmarshalBody 解析）
+            → 后端 SaveTemp → 返回 temp URL
+表单提交     → 表单字段携带该 URL
+保存记录     → 后端 saveTransform 转正（FileFields 声明）
 ```
 
-## Editor 富文本编辑器
+前端**只持有 URL**，不关心物理路径——转正时机与目录由后端声明决定。
 
-```vue
-<template>
-  <Editor v-model="formData.content" />
-</template>
+## Editor 与占位符契约
 
-<script setup>
-import Editor from '@/components/Editor/index.vue';
+- 编辑器产出标准 HTML，正文内本站图片经上传拿到相对路径
+- 保存后由后端 ContentFields 占位符化；回显时读侧已还原为完整 URL
+- 前端无需实现占位符逻辑（契约在后端唯一出口处理）
 
-const formData = ref({ content: '' });
-</script>
+## Cropper 典型流
+
+```text
+选择图片 → Cropper 裁剪 → 裁剪结果 Blob → Upload 上传 → 表单存 URL
 ```
 
-## Excel 导入组件
+个人中心头像即此流程（setting/profile）。
 
-```vue
-<template>
-  <ImportExcel @success="handleImportSuccess" />
-</template>
+## 使用规约
 
-<script setup>
-import ImportExcel from '@/components/Excel/src/ImportExcel.vue';
+- 业务页面不直接写 axios 上传，一律用公共组件
+- 组件不耦合具体模块（模块私有组件放 views 下 components/）
+- 扩展名/大小限制以服务端配置为准，前端提示仅是体验层
 
-const handleImportSuccess = (data) => {
-  // data 为解析后的数组
-  console.log(data);
-};
-</script>
-```
+## 相关
 
-## Excel 导出
-
-```typescript
-import { jsonToSheetXlsx } from '@/components/Excel/src/Export2Excel';
-
-// 导出 Excel
-jsonToSheetXlsx({
-  data: tableData.value,
-  header: {
-    name: '名称',
-    statusText: '状态',
-    createTime: '创建时间',
-  },
-  filename: '导出数据.xlsx',
-});
-```
+- [9.10 数据录入组件](/zh/frontend/form-components.html)
+- [7.1 文件上传全流程](/zh/tools/upload.html)