108 lines
3.3 KiB
Markdown
108 lines
3.3 KiB
Markdown
# 7.5 前端文件组件
|
||
|
||
:::tip 概述
|
||
本节介绍前端项目（独立 EleVue 仓库）中的文件处理组件，包括上传组件（BasicUpload）、富文本编辑器（Editor）与 Excel 导入导出组件的使用方法。组件封装了 [7.1 文件上传全流程](/zh/tools/upload.html) 的接口调用。
|
||
:::
|
||
|
||
## Upload 上传组件
|
||
|
||
```vue
|
||
<template>
|
||
<BasicUpload
|
||
v-model="formData.avatar"
|
||
:action="uploadUrl"
|
||
:maxCount="1"
|
||
/>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { BasicUpload } from '@/components/Upload';
|
||
|
||
const uploadUrl = '/api/upload/uploadFile';
|
||
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
|
||
<template>
|
||
<Editor v-model="formData.content" />
|
||
</template>
|
||
|
||
<script setup>
|
||
import Editor from '@/components/Editor/index.vue';
|
||
|
||
const formData = ref({ content: '' });
|
||
</script>
|
||
```
|
||
|
||
:::tip 富文本字段
|
||
编辑器产出的 HTML 提交后，由 Service 的 `contentFields` 配置触发 `[IMG_URL]` 占位符处理（见 [7.3 富文本处理](/zh/tools/rich-text.html)）。编辑器粘贴内容建议开启安全过滤模式防 XSS。
|
||
:::
|
||
|
||
## Excel 导入组件
|
||
|
||
```vue
|
||
<template>
|
||
<ImportExcel @success="handleImportSuccess" />
|
||
</template>
|
||
|
||
<script setup>
|
||
import ImportExcel from '@/components/Excel/src/ImportExcel.vue';
|
||
|
||
const handleImportSuccess = (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，不经过后端）
|
||
jsonToSheetXlsx({
|
||
data: tableData.value,
|
||
header: {
|
||
name: '名称',
|
||
statusText: '状态',
|
||
createTime: '创建时间',
|
||
},
|
||
filename: '导出数据.xlsx',
|
||
});
|
||
```
|
||
|
||
```typescript
|
||
// 后端导出（大数据量 / 需要权限控制时）：调用模块导出接口拿文件 URL
|
||
const res = await exampleExport(params); // 文件地址
|
||
window.open(res);
|
||
```
|
||
|
||
### 两种导出方式选择
|
||
|
||
| 方式 | 适用场景 | 特点 |
|
||
|------|---------|------|
|
||
| 前端 `jsonToSheetXlsx` | 当前页数据、无权限要求 | 零后端交互、即时下载 |
|
||
| 后端 `/export` 接口 | 全量数据、需权限与字典翻译 | `#[Permission]` 控制、`serializeMaps` 枚举转文字、分批防溢出 |
|