open-index/open-npm huggingface dataset:
npm package: @giszhc/xlsx
Description: SheetJS Spreadsheet data parser and writer
Author: sheetjs
Latest version: 0.20.4

# @giszhc/xlsx

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

------

## 📦 简介

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

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

相比原 `xlsx` 库：

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

------

## 🚀 安装

```bash
pnpm install @giszhc/xlsx
```

------

## 📖 快速开始

### 1️⃣ 导出 Excel

```js
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）

```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️⃣ 浏览器读取文件

```js
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

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

```

------

### 数据转换

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

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

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

```

------

### 文件读写

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

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

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

```

------

## ⚙️ 常用配置

### 设置列宽

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

```

------

### 多 Sheet 导出

```js
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`：

```js
import * as XLSX from 'xlsx';

```

只需替换为：

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

```

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

------

## 📚 生态与扩展

你可以基于本库实现：

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

------

## 📄 License

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