告别手动处理数据！SheetJS 终极指南：在浏览器与 Node.js 中玩转 Excel 与 CSV

在现代 Web 开发和数据处理中，与电子表格打交道是家常便饭。无论是让用户上传 Excel 报表进行分析，还是将 JSON 数据导出为 CSV 供用户下载，一个强大而灵活的库至关重要。

SheetJS（其核心库名为 xlsx）正是为此而生的 JavaScript 库。它功能全面、社区活跃，是处理电子表格数据的瑞士军刀。本文将带你从零开始，全面了解 SheetJS 的核心功能、使用方法、配置项，并通过清晰的代码示例让你快速上手。

SheetJS 是什么？

SheetJS 是一个用于读取和写入多种电子表格文件格式的 JavaScript 库。它完全用 JavaScript 编写，无需外部依赖，可以在浏览器和 Node.js 环境中无缝运行。这意味着你可以用同一套代码逻辑在前端处理后台上传的文件，也可以在服务器端批量生成报表。

核心特性一览

1. 全面的格式支持：

   • Excel: .xlsx, .xls, .xlsm, .xlsb
   • 文本格式: .csv, .tsv
   • 数据交换: JSON

2. 强大的数据处理能力：

   • 读取 (Read): 将各种格式的电子表格文件解析为 JSON、数组等可操作的数据结构。
   • 写入 (Write): 将 JSON、数组等数据生成并下载为各种格式的电子表格文件。
   • 转换 (Convert): 轻松在不同格式间进行转换，例如将 CSV 转为 Excel，或将 JSON 数组导出为 CSV。

3. 跨平台兼容：

   • 在浏览器中处理用户上传/下载的文件。
   • 在 Node.js 中执行服务器端的文件读写操作。

4. 丰富的 API：

   • 操作工作簿（Workbook）、工作表（Worksheet）、单元格（Cell）。
   • 支持单元格样式、公式、日期处理等高级功能。

快速开始：安装与引入

有两种主要方式将 SheetJS 引入你的项目。

方式一：通过 CDN 引入（用于浏览器）

直接在 HTML 文件中使用 <script> 标签引入，全局变量 XLSX 即可用。

<script src="https://cdn.sheetjs.com/xlsx-latest/package/dist/xlsx.full.min.js"></script>

方式二：使用 NPM 安装（用于 Node.js 或构建工具）

通过 npm 或 yarn 安装，便于在模块化项目中使用。

npm install xlsx
# 或
yarn add xlsx

然后，在你的 JavaScript 文件中导入：

import * as XLSX from 'xlsx';
// 或者在 CommonJS 环境中：
// const XLSX = require('xlsx');

实战代码示例

让我们通过两个最常见的场景来感受 SheetJS 的简洁与强大。

示例一：读取 Excel 文件并转换为 JSON

假设你有一个 example.xlsx 文件，你想读取它的内容并在程序中使用。

在 Node.js 环境中：

import * as XLSX from 'xlsx';

// 1. 读取文件，返回一个工作簿 (Workbook) 对象
const workbook = XLSX.readFile('example.xlsx');

// 2. 获取第一个工作表的名称
const firstSheetName = workbook.SheetNames[0];
// 3. 根据名称获取工作表 (Worksheet) 对象
const worksheet = workbook.Sheets[firstSheetName];

// 4. 将工作表转换为 JSON 对象数组
// 默认将第一行作为标题（Header）
const jsonData = XLSX.utils.sheet_to_json(worksheet);

console.log(jsonData);
// 输出: [ { name: 'Alice', age: 25 }, { name: 'Bob', age: 30 } ]

在浏览器环境中（通过文件输入框上传）：

<input type="file" id="fileUploader" />
<script>
  document.getElementById('fileUploader').addEventListener('change', function(e) {
    const file = e.target.files[0];
    const reader = new FileReader();

    reader.onload = function(e) {
      const data = new Uint8Array(e.target.result);
      // 读取二进制数据
      const workbook = XLSX.read(data, { type: 'array' });

      // ...后续操作与 Node.js 版本相同
      const worksheet = workbook.Sheets[workbook.SheetNames[0]];
      const jsonData = XLSX.utils.sheet_to_json(worksheet);
      console.log(jsonData);
    };
    reader.readAsArrayBuffer(file);
  });
</script>

示例二：将 JSON 数据写入并导出为 Excel 文件

现在，我们有一组 JSON 数据，需要让用户下载成 Excel 文件。

import * as XLSX from 'xlsx';

// 1. 准备要导出的数据
const data = [
  { name: 'Alice', age: 25, department: 'HR' },
  { name: 'Bob', age: 30, department: 'Engineering' },
  { name: 'Charlie', age: 28, department: 'Marketing' }
];

// 2. 将 JSON 数组转换为工作表 (Worksheet)
// 对象的键（name, age...）会自动成为表头
const worksheet = XLSX.utils.json_to_sheet(data);

// 3. 创建一个新的工作簿 (Workbook)
const workbook = XLSX.utils.book_new();

// 4. 将工作表添加到工作簿中，并命名为 "Employees"
XLSX.utils.book_append_sheet(workbook, worksheet, 'Employees');

// 5. 将工作簿写入文件并下载
// 在浏览器中，这会下载一个名为 'output.xlsx' 的文件
XLSX.writeFile(workbook, 'output.xlsx');

核心 API 与配置项详解

SheetJS 提供了精细的控制选项，让你能处理各种边界情况。

常用工具方法速查

重要配置选项

读取选项 (read / readFile 的第二个参数)：

• type: 指定输入数据的类型。常见值：'binary', 'base64', 'array' (浏览器中 FileReader 的 ArrayBuffer), 'buffer' (Node.js)。
• sheetStubs: 是否为空单元格生成存根对象，默认为 false。
• header: 指定输出 JSON 的标题行。可以传递一个数组（如 ['A', 'B', 'C']）或使用数字 1（表示第一行是标题）。

写入选项 (write / writeFile 的第二个参数)：

• type: 指定输出数据的类型，同上。
• bookType: 指定输出文件的格式。如 'xlsx', 'csv', 'xls'。默认为 'xlsx'。
  • 示例：导出为 CSV:

    XLSX.writeFile(workbook, 'output.csv', { bookType: 'csv' });
    

• bookSST: 是否使用共享字符串表，对于大型文件可以节省空间，默认为 false。

转换选项 (sheet_to_json 的第二个参数)：

• header: 控制如何生成 JSON 的键。
  • 1: 使用工作表第一行作为标题（默认）。
  • ['A', 'B', 'C']: 使用自定义数组作为标题。
  • null 或不设置：自动生成 A, B, C... 作为键。
• range: 解析工作表的特定范围（如 "A2:B10"）。
• defval: 当单元格为空时使用的默认值。

总结

SheetJS 以其强大的功能、简洁的 API 和出色的兼容性，成为了 JavaScript 生态中处理电子表格数据的事实标准。无论是简单的数据导出导入，还是复杂的格式转换与样式处理，它都能胜任。

记住这几个核心步骤：

1. 读: XLSX.read 或 XLSX.readFile 得到 workbook。
2. 取: 通过 SheetNames 和 Sheets 找到你要的 worksheet。
3. 转: 用 sheet_to_json 将数据变为可操作的 JSON。
4. 写: 用 json_to_sheet 准备数据，book_append_sheet 组装，最后 writeFile 输出。

现在，就尝试用 SheetJS 来优化你项目中的电子表格处理流程吧！