@giszhc/xlsx

一个基于 SheetJS 生态持续维护的 Excel 处理库，提供稳定、安全的电子表格读写能力，适用于前端与 Node.js 场景。

📦 简介

@giszhc/xlsx 提供了一套成熟的解决方案，用于：

• 从复杂的 Excel 文件中提取数据
• 生成兼容主流软件（Excel / WPS / LibreOffice）的表格文件
• 支持 .xlsx / .xls / .csv 等多种格式

相比原 xlsx 库：

• ✅ 持续维护
• ✅ 修复已知问题与漏洞
• ✅ API 保持兼容，可无缝迁移

🚀 安装

pnpm install @giszhc/xlsx

📖 快速开始

1️⃣ 导出 Excel

import * as XLSX from '@giszhc/xlsx';

const data = [
  { name: '张三', age: 18 },
  { name: '李四', age: 20 }
];

// 转换为 worksheet
const ws = XLSX.utils.json_to_sheet(data);

// 创建 workbook
const wb = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(wb, ws, 'Sheet1');

// 导出文件
XLSX.writeFile(wb, 'data.xlsx');

2️⃣ 读取 Excel（Node.js）

import * as XLSX from '@giszhc/xlsx';

const wb = XLSX.readFile('test.xlsx');
const ws = wb.Sheets[wb.SheetNames[0]];

const data = XLSX.utils.sheet_to_json(ws);
console.log(data);

3️⃣ 浏览器读取文件

import * as XLSX from '@giszhc/xlsx';

function handleFile(file) {
  const reader = new FileReader();

  reader.onload = (e) => {
    const data = new Uint8Array(e.target.result);
    const wb = XLSX.read(data, { type: 'array' });

    const ws = wb.Sheets[wb.SheetNames[0]];
    const json = XLSX.utils.sheet_to_json(ws);

    console.log(json);
  };

  reader.readAsArrayBuffer(file);
}

🧰 常用 API

创建与操作 Workbook

const wb = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(wb, ws, 'Sheet1');

数据转换

// JSON → Sheet
XLSX.utils.json_to_sheet(data);

// 数组 → Sheet
XLSX.utils.aoa_to_sheet([
  ['姓名', '年龄'],
  ['张三', 18]
]);

// Sheet → JSON
XLSX.utils.sheet_to_json(ws, {
  defval: '' // 防止空值丢失
});

文件读写

// 写文件
XLSX.writeFile(wb, 'file.xlsx');

// 读文件
XLSX.readFile('file.xlsx');

// 浏览器读取
XLSX.read(data, { type: 'array' });

⚙️ 常用配置

设置列宽

ws['!cols'] = [
  { wch: 20 },
  { wch: 10 }
];

多 Sheet 导出

const wb = XLSX.utils.book_new();

XLSX.utils.book_append_sheet(wb, ws1, 'Sheet1');
XLSX.utils.book_append_sheet(wb, ws2, 'Sheet2');

XLSX.writeFile(wb, 'multi.xlsx');

⚠️ 注意事项

• Excel 日期字段为数字格式，需要自行转换
• 大文件处理建议分批操作，避免性能问题
• 不同环境（浏览器 / Node.js）读取方式不同

🔄 迁移说明

如果你之前使用的是 xlsx：

import * as XLSX from 'xlsx';

只需替换为：

import * as XLSX from '@giszhc/xlsx';

👉 其余代码通常无需修改即可正常运行

📚 生态与扩展

你可以基于本库实现：

• Excel 导入校验（字段校验 / 类型校验）
• 批量数据导入系统
• 报表生成与自动化导出

📄 License

遵循开源协议，具体请参考项目中的 LICENSE 文件。