ExcelJS 4.0 版本升级指南：流式处理与API变更解析

ExcelJS 4.0 版本升级指南：流式处理与API变更解析

前言

ExcelJS 是一个强大的 JavaScript 库，用于处理 Excel 文件（XLSX 格式）。在 4.0 版本中，该库对流式处理 API 进行了重大改进，提供了更高效、更灵活的文件处理方式。本文将详细介绍从 3.x 升级到 4.0 版本需要注意的关键变化，并深入解析新的流式处理机制。

废弃的 API 及替代方案

createInputStream() 方法废弃

在 3.9 版本中，我们使用以下方式处理流：

stream.pipe(workbook.xlsx.createInputStream());

而在 4.0 版本中，这个方式已被废弃，取而代之的是更直观的异步读取方式：

await workbook.xlsx.read(stream)

这个变更使得 API 更加符合现代 JavaScript 的异步编程模式，提高了代码的可读性和一致性。

全新的流式读取方式

4.0 版本引入了三种不同的流式读取方法，每种方法适用于不同的场景。

1. 工作表行迭代（推荐方式）

这是性能最优的方式，比其它方法快约 20%，并且提供了流程控制能力：

const workbook = new ExcelJS.stream.xlsx.WorkbookReader('./file.xlsx');
for await (const worksheetReader of workbookReader) {
  for await (const row of worksheetReader) {
    // 处理每一行数据
    
    // 可以使用 continue, break, return 控制流程
  }
}

优势分析：

• 最佳性能表现
• 直观的异步迭代器模式
• 完全控制处理流程
• 内存效率高，适合大文件处理

2. 事件迭代方式

这种方式提供了更细粒度的事件控制：

const options = {
  sharedStrings: 'emit',
  hyperlinks: 'emit',
  worksheets: 'emit',
};
const workbook = new ExcelJS.stream.xlsx.WorkbookReader('./file.xlsx', options);
for await (const {eventType, value} of workbook.parse()) {
  switch (eventType) {
    case 'shared-strings':
      // 处理共享字符串
    case 'worksheet':
      // 处理工作表读取器
    case 'hyperlinks':
      // 处理超链接读取器
  }
}

适用场景：

• 需要分别处理不同类型的数据
• 需要自定义处理逻辑
• 需要访问共享字符串或超链接等特定数据

3. 可读流方式

这是最传统的 Node.js 流式处理方式：

const options = {
  sharedStrings: 'emit',
  hyperlinks: 'emit',
  worksheets: 'emit',
};
const workbookReader = new ExcelJS.stream.xlsx.WorkbookReader('./file.xlsx', options);
workbookReader.read();
workbookReader.on('worksheet', worksheet => {
  worksheet.on('row', row => {
    // 处理行数据
  });
});
workbookReader.on('shared-strings', sharedString => {
  // 处理共享字符串
});
workbookReader.on('hyperlinks', hyperlinksReader => {
  // 处理超链接
});
workbookReader.on('end', () => {
  // 处理完成
});
workbookReader.on('error', (err) => {
  // 错误处理
});

特点：

• 基于事件的传统处理模式
• 适合已经熟悉 Node.js 流的开发者
• 可以处理各种类型的事件

升级建议

1. 性能优先：对于大多数情况，推荐使用第一种行迭代方式，它提供了最佳性能和流程控制。

2. 渐进式迁移：如果现有代码大量使用流式处理，可以先迁移到第三种方式，再逐步重构为更高效的方式。

3. 错误处理：无论选择哪种方式，都要确保妥善处理错误事件，避免未捕获的异常。

4. 内存管理：对于超大文件，流式处理的优势更加明显，可以显著降低内存使用。

总结

ExcelJS 4.0 的流式处理 API 重构带来了显著的性能提升和使用体验改进。通过提供多种处理方式，开发者可以根据具体需求选择最适合的方法。理解这些变化将帮助你更高效地处理 Excel 文件，特别是在处理大型数据集时。

升级到 4.0 版本后，建议重新评估现有的 Excel 处理逻辑，充分利用新 API 的优势，优化应用程序的性能和资源使用效率。