import{_ as i,o as a,c as t,a2 as h}from"./chunks/framework.B-QBKwc1.js";const g=JSON.parse('{"title":"Excel 导入导出组件","description":"本节介绍前端项目中的 Excel 导入导出组件，包括导入组件（ImportExcel）和导出功能（Export2Excel）的使用方法，并说明前端解析与后端导入两条链路的选择。","frontmatter":{},"headers":[],"relativePath":"zh/frontend/excel-components.md","filePath":"zh/frontend/excel-components.md"}'),n={name:"zh/frontend/excel-components.md"};function l(k,s,p,e,F,r){return a(),t("div",null,[...s[0]||(s[0]=[h(`

9.11 Excel 导入导出组件 ​

概述

本节介绍前端项目中的 Excel 导入导出组件，包括导入组件（ImportExcel）和导出功能（Export2Excel）的使用方法，并说明前端解析与后端导入两条链路的选择。

导入组件（前端解析） ​

vue
<template>
  <el-button @click="handleImport">导入</el-button>
  <ImportExcel @success="onImportSuccess" />
</template>

<script setup>
import ImportExcel from '@/components/Excel/src/ImportExcel.vue';

const onImportSuccess = (data) => {
  // data 为解析后的数组，每项是对象
  console.log(data);
};
</script>

前端解析 vs 后端导入

后端导入对接 ​

vue
<template>
  <el-upload
    :action="'/api/example/import'"
    :headers="{ Authorization: \`Bearer \${token}\` }"
    :on-success="handleImportSuccess"
    accept=".xls,.xlsx"
  >
    <el-button type="primary">导入</el-button>
  </el-upload>
</template>

<script setup>
const handleImportSuccess = (response) => {
  if (response.code === 0) {
    const { count, errors } = response.data;
    if (errors.length === 0) {
      ElMessage.success(\`成功导入 \${count} 条数据\`);
    } else {
      ElMessage.warning(\`成功 \${count} 条，失败 \${errors.length} 条\`);
      // errors: [{ row: 3, name: '...', reason: '...' }]
    }
  }
};
</script>

导出功能（前端导出） ​

typescript
import { jsonToSheetXlsx } from '@/components/Excel/src/Export2Excel';

const handleExport = () => {
  jsonToSheetXlsx({
    data: tableData.value,
    header: {
      name: '名称',
      typeText: '类型',
      statusText: '状态',
      createTime: '创建时间',
    },
    filename: '导出数据.xlsx',
  });
};

后端导出对接（推荐） ​

typescript
// 调用后端导出接口，返回文件 URL（全量数据 + 权限控制 + 字典翻译）
const handleExport = async () => {
  const res = await exampleExport(searchParams.value);   // 文件地址
  window.open(res);
};

后端接口由 Controller::_export() 封装（#[OperationLog(TYPE_EXPORT)] + #[Permission] + ExcelService），大数据量时 Service 内改用 chunkExport 分批导出。

导入模板下载 ​

typescript
// 下载导入模板
const handleDownloadTemplate = async () => {
  const url = await exampleExportTemplate();
  window.open(url);
};

导入导出注意事项 ​

场景说明
大数据量导出后端 chunkExport 分批导出（回调取空终止），避免内存溢出
导入模板第一行为表头，第二行起为数据（行号反馈 row = 索引 + 2）
字段映射后端 headerMap 配置表头与字段的对应关系（未声明列忽略）
枚举翻译导入时 DictCacheService::getValue 文本转值，导出时 serializeMaps 值转文本
文件限制仅 xls/xlsx、10MB 上限、finfo MIME 检测（_import 内置）

两种方案选择 ​

方式适用场景校验
前端 ImportExcel 解析导入预览、轻量转换仅格式解析
后端 /import 接口正式导入FormRequest/钩子/唯一性/字典全量校验

相关文档 ​

`,20)])])}const y=i(n,[["render",l]]);export{g as __pageData,y as default};