一、NPOI核心概念解析

1.1 什么是NPOI

NPOI是Apache POI的.NET移植版本，作为开源的Office文档操作库，支持对Excel 97-2019（.xls/.xlsx）、Word、PowerPoint等格式的无Office软件依赖操作。其核心优势在于：

• 跨平台兼容性：支持.NET Framework 2.0+及.NET Core
• 高性能处理：内存占用优化，支持百万级数据操作
• 完整功能覆盖：支持单元格格式、公式、图表、数据验证等高级功能

1.2 版本选择指南

版本类型	适用场景	依赖项
NPOI 2.5.5	传统.NET Framework项目	System.Drawing
NPOI 2.6.0+	.NET Core/.NET 5+跨平台项目	SkiaSharp（替代方案）
NPOI.OOXML	仅需处理xlsx格式的轻量级场景	减少依赖体积

建议生产环境使用2.6.0+版本，其修复了2.5.x系列存在的内存泄漏问题，并优化了大数据量导出性能。

二、基础操作实战

2.1 环境配置三步法

1. 通过NuGet安装核心包：

   Install-Package NPOI -Version 2.6.0
   Install-Package NPOI.OOXML  # 如需xlsx支持

2. 添加命名空间：

   using NPOI.SS.UserModel;
   using NPOI.XSSF.UserModel; // xlsx专用
   using NPOI.HSSF.UserModel; // xls专用

3. 创建测试文件目录（建议使用Path.Combine处理路径）

2.2 Excel文件读写全流程

写入操作示例

// 创建工作簿
IWorkbook workbook = new XSSFWorkbook(); // xlsx格式
// IWorkbook workbook = new HSSFWorkbook(); // xls格式
// 创建工作表
ISheet sheet = workbook.CreateSheet("员工数据");
// 创建行与单元格
IRow headerRow = sheet.CreateRow(0);
headerRow.CreateCell(0).SetCellValue("姓名");
headerRow.CreateCell(1).SetCellValue("年龄");
// 填充数据
IRow dataRow = sheet.CreateRow(1);
dataRow.CreateCell(0).SetCellValue("张三");
dataRow.CreateCell(1).SetCellValue(28);
// 保存文件
using (FileStream fs = new FileStream("员工表.xlsx", FileMode.Create))
{
    workbook.Write(fs);
}

读取操作示例

using (FileStream fs = new FileStream("员工表.xlsx", FileMode.Open))
{
    IWorkbook workbook = new XSSFWorkbook(fs);
    ISheet sheet = workbook.GetSheetAt(0);
    for (int i = 0; i <= sheet.LastRowNum; i++)
    {
        IRow row = sheet.GetRow(i);
        if (row != null)
        {
            string name = row.GetCell(0)?.ToString();
            double age = row.GetCell(1)?.NumericCellValue ?? 0;
            Console.WriteLine($"{name}, {age}岁");
        }
    }
}

三、高级功能实现

3.1 单元格格式控制

// 创建单元格样式
ICellStyle headerStyle = workbook.CreateCellStyle();
IFont headerFont = workbook.CreateFont();
headerFont.FontName = "微软雅黑";
headerFont.FontHeightInPoints = 12;
headerFont.Boldweight = (short)FontBoldWeight.Bold;
headerStyle.SetFont(headerFont);
headerStyle.FillForegroundColor = IndexedColors.Grey25Percent.Index;
headerStyle.FillPattern = FillPattern.SolidForeground;
// 应用样式
headerRow.GetCell(0).CellStyle = headerStyle;

3.2 公式处理技巧

// 写入SUM公式
IRow summaryRow = sheet.CreateRow(10);
summaryRow.CreateCell(0).SetCellValue("总计");
ICell formulaCell = summaryRow.CreateCell(1);
formulaCell.SetCellFormula("SUM(B2:B10)");
// 读取公式结果
double result = formulaCell.NumericCellValue;

3.3 大数据量优化方案

1. 分块写入：每10000行执行一次workbook.Write()
2. 流式处理：使用SXSSFWorkbook替代XSSFWorkbook
   ```csharp
   // 创建流式工作簿（内存中保留100行）
   SXSSFWorkbook sxssfWorkbook = new SXSSFWorkbook(100);
   ISheet largeSheet = sxssfWorkbook.CreateSheet(“大数据”);

for (int i = 0; i < 100000; i++)
{
IRow row = largeSheet.CreateRow(i);
row.CreateCell(0).SetCellValue($”数据{i}”);
// 定期手动刷新到磁盘
if (i % 5000 == 0)
{
((SXSSFSheet)largeSheet).FlushRows(500); // 刷新500行到临时文件
}
}

# 四、常见问题解决方案
## 4.1 中文乱码问题
- 原因：未正确设置字体编码
- 解决方案：
```csharp
ICellStyle chineseStyle = workbook.CreateCellStyle();
IFont chineseFont = workbook.CreateFont();
chineseFont.FontName = "宋体"; // 或"Microsoft YaHei"
chineseStyle.SetFont(chineseFont);

4.2 内存溢出处理

• 现象：处理10万+数据时抛出OutOfMemoryException
• 优化方案：

1. 使用SXSSFWorkbook替代XSSFWorkbook
2. 调整JVM参数（如-Xmx2g）
3. 分批次处理数据，每次处理5万行

4.3 版本兼容性

• xls与xlsx格式差异：
  | 特性 | xls (HSSF) | xlsx (XSSF) |
  |——————-|——————|——————-|
  | 最大行数 | 65,536 | 1,048,576 |
  | 最大列数 | 256 | 16,384 |
  | 文件体积 | 较大 | 较小 |

五、最佳实践建议

1. 资源释放：确保所有FileStream和Workbook对象都包含在using语句中
2. 异常处理：捕获以下常见异常：
   • IOException：文件读写错误
   • InvalidOperationException：格式不匹配
   • ArgumentException：参数无效
3. 性能测试：建议对10万+数据量进行基准测试，对比不同实现方案的耗时
4. 日志记录：在关键操作节点添加日志，便于问题排查

六、扩展应用场景

1. 模板导出：预先设计Excel模板，通过NPOI填充动态数据
2. 数据验证：设置下拉列表、数字范围等验证规则
3. 图表生成：创建柱状图、折线图等可视化元素
4. 多Sheet管理：动态创建和管理多个工作表

通过系统掌握本手册介绍的技术要点，开发者能够高效解决90%以上的Excel操作需求，显著提升办公自动化项目的开发效率。建议结合官方文档（https://github.com/nissl-lab/npoi）进行深入学习，定期关注版本更新日志获取最新功能。