跳转至

我该用哪套 API

LiteExcel 有多个入口,第一次用容易不知道从哪下手。这一页帮你 30 秒选定。

三十秒决策表

你的情况 用这个 为什么
日常读写、要设样式 对象模型 Excel.Create() 最直观,链式调用
已有 List<T> 要导出 Excel.Write(path, list) 一行搞定,自动映射表头
读进来就是 List<T> Excel.Read<T>(path) 同上,反向
数据来自数据库 Excel.Create(DataTable) 免手工转换
只处理裸数据、不要样式 SheetData + XlsxWriter 轻量,无对象开销
几十万行大文件 XlsxStreamWriter 不占内存
要读一个超大的表 Excel.EnumerateRows 逐行拉取,可提前终止
打开用户上传的文件 Excel.Open(path) 按扩展名自动路由五种格式

决策流程图

flowchart TD
    A[你要做什么?] --> B{数据已经是<br/>List&lt;T&gt; 或 DataTable?}
    B -->|是| C[Excel.Write / Excel.Create<br/>自动映射表头]
    B -->|否| D{数据量?}
    D -->|几十万行以上| E[XlsxStreamWriter<br/>流式写,不占内存]
    D -->|几万行以内| F{需要样式吗?}
    F -->|需要| G[对象模型<br/>Excel.Create → Worksheet]
    F -->|不需要| H[SheetData + XlsxWriter<br/>轻量]

五种「取单元格」的区别

这是最容易绕晕的地方。记住一句话就够:单格用 Cell(),整块用 Range()。

写法 返回 什么时候用
ws.Cell("B3") Cell 最常用。知道地址时
ws.Cell(3, 2) Cell 坐标是算出来的(循环里)
ws.Cells[3, 2] Cell 同上,语法糖
ws.Range("A1:D10") ExcelRange 一次处理一块区域
ws.Cell("B3").Value object? 只要值,不要 Cell 对象

坐标规则不统一

ws.Cell(row, col) 是 1-based;而 range.Cell(rowOffset, colOffset) 是 0-based。 这是本库最容易搞混的一点。

三种「读文件」的区别

入口 支持格式 适用
Excel.Open(path) 全部五种 需要看工作表结构、样式、要改内容
Excel.Read<T>(path) 仅 xlsx / xlsm 直接映射成 List<T>,最省事
Excel.ReadSheet(path) 按扩展名路由 想要 SheetData 裸数据

为什么 Excel.Read<T> 只支持两种格式

xls / xlsb 是二进制格式,直接映射为对象需要额外的类型推断,暂未实现。 用 Excel.Open 打开后再逐格读取即可。

什么时候用低层 API

低层 API(SheetData / XlsxReader / XlsxWriter / XlsxStreamWriter)适合:

  • 数据是裸的二维表,不需要单元格级样式
  • 追求最少内存占用
  • 从别的系统对接,只做格式转换

日常业务代码优先用对象模型 API —— 可读性和可维护性更好。

相关