# 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` 枚举转文字、分批防溢出 |