我该用哪套 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<T> 或 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 —— 可读性和可维护性更好。