React 项目中封装 Excel 导入导出组件：技术分享与实践
文章目录
- 前言
- 一、为什么需要封装 Excel 组件？
- 二、技术选型
- 三、核心实现
- 1. 安装依赖
- 2. 封装Excel导出
- 3. 封装导入组件 （UploadExcel）
- 总结
前言
在 React 项目中，处理 Excel 文件的导入和导出是常见的业务需求。无论是导出报表数据供用户下载，还是让用户上传 Excel 文件进行数据解析，一个高效、易用的组件都能极大提升开发效率和用户体验。本文将分享如何在 React 项目中封装一个通用的 Excel 导入导出组件，涵盖核心实现思路、代码示例以及最佳实践。
一、为什么需要封装 Excel 组件？
- 统一处理逻辑：避免在多个页面重复编写 Excel 解析或生成代码。
- 提升用户体验：通过统一的 UI 和交互，降低用户学习成本。
- 减少错误：集中处理文件格式校验、数据转换等易错环节。
- 可扩展性：支持自定义配置（如列映射、样式调整等）。
二、技术选型
- 导出 Excel：使用
xlsx库 &file-saver。 - 导入 Excel：使用
xlsx库解析文件内容。 - UI 框架：基于 Ant Design 的 Upload 组件或自定义按钮。
三、核心实现
1. 安装依赖
npm install xlsx file-saver @ant-design/icons# 或使用 yarnyarn add xlsx file-saver @ant-design/icons
2. 封装Excel导出
根据泛型传入不同的data数据类型和动态传递header表头
import * as XLSX from "xlsx";
import { saveAs } from "file-saver";/*** 导出Excel* @param data* @param header*/
export function exportExcel<T>(data: T[], header: string[]) {const worksheet = XLSX.utils.json_to_sheet(data, { header });// 创建工作簿const workbook = XLSX.utils.book_new();// 将工作表添加到工作簿XLSX.utils.book_append_sheet(workbook, worksheet, "Sheet1");// 将工作簿转换为二进制数据const excelBuffer = XLSX.write(workbook, { bookType: "xlsx", type: "array" });// 创建 Blob 对象const blob = new Blob([excelBuffer], { type: "application/octet-stream" });// 使用 file-saver 库保存文件saveAs(blob, "exported_data.xlsx");
}使用示例
import {useState} from 'react'
import { exportExcel } from "@/utils/exprotExcel";
// 这个是antd的table组件的表格多选框 selectedRowKeys, setSelectedRowKeys要绑定的状态值
const [selectedRowKeys, setSelectedRowKeys] = useState<React.Key[]>([]);
const [selectRows, setSelectRows] = useState<IBill[]>([]);
const header = ["accountNo","status","roomNo","carNo","tel","costName1","costName2","costName3","startDate","endDate","preferential","money","pay",
];// 多选const onSelectChange = (selectedRowKeys: React.Key[],selectedRows: IBill[]) => {setSelectedRowKeys(selectedRowKeys);setSelectRows(selectedRows);};// 多选框配置项const rowSelection = {selectedRowKeys,onChange: onSelectChange,preserveSelectedRowKeys: true,};// 这下面是结构
<Tableloading={loading}dataSource={billList}columns={columns}pagination={false}rowKey={(record) => record.accountNo}scroll={{ x: 1200 }}rowSelection={rowSelection}/><Button// 使用封装好的Excel导出组件type="primary"onClick={() => exportExcel(selectRows, header)}icon={<DownloadOutlined />}disabled={disabled}>导出为Excel
</Button>
3. 封装导入组件 （UploadExcel）
import { Upload, message } from "antd";
import type { UploadProps } from "antd";
import { InboxOutlined } from "@ant-design/icons";
const { Dragger } = Upload;import * as XLSX from "xlsx";interface ExcelRowItem {[key: number]: string; // 索引签名，允许任意数字键
}interface IParms<U> {setStaffList: (staffList: (prev: U[]) => U[]) => void;headers: (keyof U)[];
}
// 处理导入的Excel数据
function handleImpotedJson<T>(jsonArr: ExcelRowItem[],headers: (keyof T)[] // 将 headers 明确为 T 的键数组
) {// 去掉表头jsonArr.splice(0, 1);const jsonArrData: T[] = jsonArr.map((item: ExcelRowItem) => {console.log(item, "item");// 这样做可以避免不用初始化对象，不用硬编码Partialconst jsonObj: Partial<T> = {};// const jsonObj: T = {// key: Math.floor(Math.random() * 10000000),// name: item[0],// region: item[1],// role: item[2],// phone: item[3],// };// 动态生成表头headers.forEach((header, index) => {const value = item[index];if (value !== undefined) {jsonObj[header] = value as T[keyof T];}});return jsonObj as T;});console.log(jsonArrData, "jsonArrData");return jsonArrData;
}/*** Excel上传组件* @param param0 传参需要：1.useState表格数据列表 2.表头信息 3.传表头的泛型* @returns*/
function UploadExcel<U>({ setStaffList, headers }: IParms<U>) {const props: UploadProps = {name: "file",multiple: true,accept: ".xls,.xlsx", // 只允许上传 Excel 文件action: "https://www.demo.com/import",onChange(info) {console.log("我同时触发了onChange和onDrop");const { status } = info.file;if (status !== "uploading") {const file = info.file.originFileObj; //if (file) {const reader = new FileReader();reader.onload = (e) => {const target = e.target?.result as ArrayBuffer;if (target) {const data = target; // 安全访问const workbook = XLSX.read(data, { type: "binary" });const first_worksheet = workbook.Sheets[workbook.SheetNames[0]];const jsonArr = XLSX.utils.sheet_to_json(first_worksheet, {header: 1,});const res = handleImpotedJson<U>(jsonArr as ExcelRowItem[],headers);console.log(res, "我是最后的结果");setStaffList((prevStaffList) => {return [...prevStaffList, ...res];});// 添加这一行，开始读取文件reader.readAsArrayBuffer(file);}}if (status === "done") {message.success(`${info.file.name} 文件已成功上传.`);} else if (status === "error") {message.error(`${info.file.name} 文件上传失败.`);}},onDrop(e) {console.log("我开始拖拽了", e.dataTransfer.files);},};return (// 这个是antd的上传组件<><Dragger {...props}><p className="ant-upload-drag-icon"><InboxOutlined /></p><p className="ant-upload-text">点击或拖拽上传文件哦！！！</p><p className="ant-upload-hint">支持单个文件或批量上传。严禁上传公司数据或其他受禁文件。</p></Dragger></>);
}export default UploadExcel;使用示例：
也是引入组件，传表头，和你的修改状态的setState
import UploadExcel from "@/components/UploadExcel";
import {useState} from 'react'const [staffList, setStaffList] = useState<IStaff[]>([]);const header: StaffKeys[] = ["name", "region", "role", "phone"];<UploadExcel<StaffMemberData>headers={header}setStaffList={setStaffList}/>
总结
通过封装 Excel 导入导出组件，我们可以将重复的逻辑抽象为可复用的模块，提升开发效率和代码质量。关键点包括：
- 使用
xlsx库处理核心逻辑。 - 结合 Ant Design 等 UI 框架提升交互体验。
- 通过配置化（如列映射、泛型约束）满足不同场景需求。