前言
在 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
# 或使用 yarn
yarn 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,
};
// 这下面是结构
<Table
loading={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");
// 这样做可以避免不用初始化对象，不用硬编码Partial
const 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 框架提升交互体验。
- 通过配置化（如列映射、泛型约束）满足不同场景需求。