签入版本

RXThinkCMF_Laravel13_EleVue/zh/tools/file-components.md

@@ -1,7 +1,7 @@
 # 7.5 前端文件组件
 
 :::tip 概述
-本节介绍前端项目中的文件处理组件，包括上传组件（BasicUpload）和图片预览组件的使用方法。
+本节介绍前端项目（独立 EleVue 仓库）中的文件处理组件，包括上传组件（BasicUpload）、富文本编辑器（Editor）与 Excel 导入导出组件的使用方法。组件封装了 [7.1 文件上传全流程](/zh/tools/upload.html) 的接口调用。
 :::
 
 ## Upload 上传组件
@@ -23,6 +23,19 @@ const formData = ref({ avatar: '' });
 </script>
 ```
 
+:::tip 字段值约定
+`BasicUpload` 绑定的值建议存 **`filePath`（相对路径）**——提交表单后由 Service 的 `fileFields` 归一化，读取时自动补全 `FILE_DOMAIN_URL` 域名。上传需携带 `Authorization: Bearer <token>` 请求头（组件内部或 http 封装统一处理）。
+:::
+
+### 常用属性
+
+| 属性 | 说明 |
+|------|------|
+| `v-model` | 绑定的文件值（相对路径） |
+| `action` | 上传接口地址（`/api/upload/uploadFile`） |
+| `maxCount` | 最大上传数量（1 = 单文件，如头像） |
+| `:data="{ type: 'image' }"` | 上传类型（image 校验图片后缀白名单，两类均存入 `temp/` 临时目录） |
+
 ## Editor 富文本编辑器
 
 ```vue
@@ -37,6 +50,10 @@ const formData = ref({ content: '' });
 </script>
 ```
 
+:::tip 富文本字段
+编辑器产出的 HTML 提交后，由 Service 的 `contentFields` 配置触发 `[IMG_URL]` 占位符处理（见 [7.3 富文本处理](/zh/tools/rich-text.html)）。编辑器粘贴内容建议开启安全过滤模式防 XSS。
+:::
+
 ## Excel 导入组件
 
 ```vue
@@ -48,18 +65,23 @@ const formData = ref({ content: '' });
 import ImportExcel from '@/components/Excel/src/ImportExcel.vue';
 
 const handleImportSuccess = (data) => {
-  // data 为解析后的数组
+  // data 为解析后的数组（前端本地解析预览场景）
   console.log(data);
 };
 </script>
 ```
 
+:::tip 前端解析 vs 后端导入
+- **后端导入（推荐，走业务校验）**：`el-upload` 直传 `/api/{module}/import`，由 Service 逐行 `add()`（字典反查、唯一校验、事务），见 [7.4 数据导入导出](/zh/tools/excel.html)；
+- **前端解析**：`ImportExcel` 组件用 `xlsx` 库本地解析为数组，适合导入前预览、无业务校验的场景。
+:::
+
 ## Excel 导出
 
 ```typescript
 import { jsonToSheetXlsx } from '@/components/Excel/src/Export2Excel';
 
-// 导出 Excel
+// 前端直接导出（本地数据组装为 Excel，不经过后端）
 jsonToSheetXlsx({
   data: tableData.value,
   header: {
@@ -69,4 +91,17 @@ jsonToSheetXlsx({
   },
   filename: '导出数据.xlsx',
 });
-```
+```
+
+```typescript
+// 后端导出（大数据量 / 需要权限控制时）：调用模块导出接口拿文件 URL
+const res = await exampleExport(params);   // 文件地址
+window.open(res);
+```
+
+### 两种导出方式选择
+
+| 方式 | 适用场景 | 特点 |
+|------|---------|------|
+| 前端 `jsonToSheetXlsx` | 当前页数据、无权限要求 | 零后端交互、即时下载 |
+| 后端 `/export` 接口 | 全量数据、需权限与字典翻译 | `#[Permission]` 控制、`serializeMaps` 枚举转文字、分批防溢出 |