79 lines
3.0 KiB
Markdown
79 lines
3.0 KiB
Markdown
# 9.11 Excel 导入导出组件
|
||
|
||
:::tip 概述
|
||
前端 Excel 能力由 components/Excel 与 importFile 组件 + xlsx 库提供：导入走文件上传接口拿统计结果，导出走导出接口拿文件 URL 再下载。前后端协作协议见 [7.4 数据导入导出](../tools/excel)。
|
||
:::
|
||
|
||
## 组件与工具
|
||
|
||
| 模块 | 职责 |
|
||
|------|------|
|
||
| components/Excel | Excel 处理组件（导入解析/导出生成的前端封装） |
|
||
| components/importFile | 导入文件入口组件（选文件→上传→结果展示） |
|
||
| utils/downloadFile | 文件下载工具（导出 URL 触发浏览器下载） |
|
||
| xlsx（依赖） | SheetJS 解析/生成 |
|
||
|
||
## 导入协作流
|
||
|
||
```text
|
||
1. 页面"导入"按钮（v-permission="sys:xxx:import"）→ importFile 组件
|
||
2. 选择 xls/xlsx → POST /api/{module}/import（multipart，字段 file）
|
||
3. 后端 excel.ReadSheet → 逐行校验写入
|
||
4. 返回统计：{total, success, failed, reasons[]}
|
||
5. 组件展示结果（成功 N 条 / 失败 M 条 + 逐行原因列表）
|
||
6. 关闭后刷新列表
|
||
```
|
||
|
||
真实响应示例（example 导入）：
|
||
|
||
```json
|
||
{ "total": 100, "success": 98, "failed": 2,
|
||
"reasons": ["第5行：案例名称为空", "第17行：写入失败 Duplicate entry..."] }
|
||
```
|
||
|
||
## 导出协作流
|
||
|
||
```text
|
||
1. 页面"导出"按钮（v-permission="sys:xxx:export"）
|
||
2. 携带当前列表筛选参数 GET /api/{module}/export
|
||
（导出=所见：与列表同套筛选，含数据权限过滤）
|
||
3. 后端 ChunkQuery 分批 + excel.WriteSheet → 返回文件 URL
|
||
4. downloadFile 触发下载
|
||
```
|
||
|
||
## 导入模板约定
|
||
|
||
```text
|
||
表头 = 表单字段名（导出文件即导入模板——"导出→改数据→导入"闭环）
|
||
单元格全字符串解析（TrimSpace）；空行跳过
|
||
列序与后端 cellAt(row, N) 索引对应——改列序需同步后端解析
|
||
```
|
||
|
||
## 大文件注意
|
||
|
||
| 场景 | 说明 |
|
||
|------|------|
|
||
| 导出大结果集 | 后端 ChunkQuery 500/页 防 OOM；生成仍为单文件（Excel 行数上限 104 万内） |
|
||
| 导入大文件 | 逐行独立成败；超大批量建议分批导入（控制单请求耗时） |
|
||
| 导出文件有效期 | 导出文件落 /upload/temp/——受 tempExpireDays 清理，及时下载 |
|
||
|
||
## 新页面接入步骤
|
||
|
||
```text
|
||
1. 后端：Req（ImportReq 带 File 字段 / ExportReq 带筛选字段）+ logic 实现
|
||
（参照 example 的 Import/Export 真实代码）
|
||
2. 权限节点：import/export（生成器默认自动建）
|
||
3. 前端：importFile 组件 + 导出按钮（downloadFile）
|
||
4. 列表页操作区挂两个按钮（v-permission 对齐）
|
||
```
|
||
|
||
## 排障
|
||
|
||
| 症状 | 原因 |
|
||
|------|------|
|
||
| 导入全部失败 | 表头/列序与后端解析不匹配；对照导出模板 |
|
||
| 导入部分失败 | 看 reasons 逐行原因（唯一冲突/必填缺失/字典值非法） |
|
||
| 导出内容与列表不符 | ExportReq 未带筛选字段或未走 applyFilters（对照 7.4 规范） |
|
||
| 导出 404 | 文件已被 temp 清理；重新导出立即下载 |
|
||
| 导出超时 | 结果集过大——确认 ChunkQuery 已接；拆分筛选条件分批导 |
|