processing-excel-files

处理 Excel 文件

使用 xlsx-populate 库编辑和处理 Excel 文件，同时完美保留原有格式。

适用场景

• 用户希望编辑现有 Excel 文件，同时不破坏格式
• 处理具有复杂布局或合并单元格的 .xlsx 文件
• 需要向现有文件添加公式、样式或新工作表
• 根据模板创建 Excel 报告

不适用场景

• 只需读取 Excel 中的数据（建议改用 xlsx 库，以获得更好的性能）
• 从零创建简单的 Excel 文件，且无需考虑格式

快速入门

const XlsxPopulate = require('xlsx-populate');

// Load and edit
const workbook = await XlsxPopulate.fromFileAsync('input.xlsx');
workbook.sheet(0).cell('A1').value('Updated');
await workbook.toFileAsync('output.xlsx');

安装

npm install xlsx-populate

核心操作

1. 加载并保留格式

const workbook = await XlsxPopulate.fromFileAsync('file.xlsx');
const sheet = workbook.sheet(0);

// All original formatting is preserved automatically
sheet.cell('A1').value('New Value');
await workbook.toFileAsync('output.xlsx');

2. 添加公式

// Use formulas, not hardcoded values
sheet.cell('D10').formula('=SUM(D2:D9)');
sheet.cell('E5').formula('=(C5-B5)/B5');  // Growth rate

3. 应用样式

sheet.cell('A1').style({
  bold: true,
  fontSize: 14,
  fill: '4472C4',
  fontColor: 'FFFFFF'
});

4. 管理工作表

// Add new sheet
const newSheet = workbook.addSheet('Summary');

// Reorder sheets
workbook.sheets()[2].move(0);

// Rename sheet
workbook.sheet(0).name('Cover Page');

5. 合并单元格

sheet.range('A1:D1').merged(true);
sheet.range('A1:D1').style({
  horizontalAlignment: 'center'
});

高级模式

批量写入数据：有关大型数据集处理，请参阅 [BATCH-OPERATIONS.md]
公式模式：有关财务建模规范，请参阅 [FORMULAS.md]
样式指南：有关配色方案和格式设置，请参阅 [STYLES.md]
完整示例：有关实际应用场景，请参阅 [EXAMPLES.md]

最佳实践

1. 始终保留原文件：切勿覆盖源文件

   await workbook.toFileAsync('output.xlsx');  // ✅ New file
   // NOT: await workbook.toFileAsync('input.xlsx');  // ❌ Don't overwrite
   

2. 使用公式进行计算：让 Excel 完成计算

   sheet.cell('B10').formula('=SUM(B2:B9)');  // ✅
   // NOT: sheet.cell('B10').value(calculateSum());  // ❌
   

3. 妥善处理错误：

   try {
     const workbook = await XlsxPopulate.fromFileAsync('file.xlsx');
     // ... operations
     await workbook.toFileAsync('output.xlsx');
   } catch (error) {
     console.error('Excel operation failed:', error.message);
   }
   

常见问题

问：文件大小显著增加了？
答：这是正常现象——xlsx-populate 会保留更多元数据。如果文件大小至关重要，请使用 xlsx 库。

问：公式没有计算？
答：公式会被保留，但只有在 Excel 中打开文件时才会计算。使用 data_only=True 读取计算后的值。

问：如何检查合并的单元格？
答：const merges = sheet._mergeCells;

参考资料

• xlsx-populate GitHub
• 库文档：node_modules/xlsx-populate/docs/