21. 流式读取 / 进度回调 / 追加数据¶
本章介绍大文件场景的流式读取、带进度读取、追加数据与流式写入。
Warning
流式读取 / 追加 / 流式写入仅支持 xlsx / xlsm。
21.1 流式读取 StreamRows¶
逐行回调,不驻留内存,适合大文件。仅支持 xlsx / xlsm:
var sheet = new SheetData
{
SheetName = "Scores",
Headers = new() { "Name", "Score" },
Rows = new()
{
new Cell[] { Cell.FromText("Alice"), Cell.FromNumber(95) },
new Cell[] { Cell.FromText("Bob"), Cell.FromNumber(88) },
},
};
Excel.Write("scores.xlsx", sheet);
Excel.StreamRows("scores.xlsx", "Scores", row =>
{
foreach (var cell in row)
Console.Write($"{cell.GetString()} | ");
Console.WriteLine();
});
输出:
21.2 带进度读取 ReadWithProgress¶
先快速扫描总数据行数,再流式逐行读取,current 从 1 递增到 total(数据行数,不含表头):
var sheet = new SheetData
{
SheetName = "Scores",
Headers = new() { "Name", "Score" },
Rows = new()
{
new Cell[] { Cell.FromText("Alice"), Cell.FromNumber(95) },
new Cell[] { Cell.FromText("Bob"), Cell.FromNumber(88) },
new Cell[] { Cell.FromText("Cara"), Cell.FromNumber(72) },
},
};
Excel.Write("progress.xlsx", sheet);
Excel.ReadWithProgress("progress.xlsx", 0, (current, total) =>
Console.WriteLine($"{current}/{total}"));
输出:
21.3 追加数据 Append¶
Excel.Append(path, SheetData, WorkbookProperties?)(SheetData 见附录 B.1):同名 sheet 合并列后追加行;不同名则作为新 sheet 加入;文件不存在时创建。仅支持 xlsx / xlsm:
// 先写 3 行
var sheet1 = new SheetData
{
SheetName = "Data",
Headers = new() { "ID" },
Rows = new()
{
new Cell[] { Cell.FromNumber(1) },
new Cell[] { Cell.FromNumber(2) },
new Cell[] { Cell.FromNumber(3) },
},
};
Excel.Write("append.xlsx", sheet1);
// 追加 2 行
var appendData = new SheetData
{
SheetName = "Data",
Headers = new() { "ID" },
Rows = new()
{
new Cell[] { Cell.FromNumber(4) },
new Cell[] { Cell.FromNumber(5) },
},
};
Excel.Append("append.xlsx", appendData);
// 读回验证
var read = Excel.ReadAsDataTable("append.xlsx");
Console.WriteLine(read.Rows.Count);
输出:
追加不改变既有 sheet 顺序,工作表级保留 rels 可继续复用(xlsm 追加不丢宏)。
追加时表头对齐:同名 sheet 追加时,新表头中不存在于原表头的列会追加到原表头末尾;数据行按列名对齐到合并后的列位置;缺失列补 Empty:
// 原文件表头:ID | Name
Excel.Write("align.xlsx", new SheetData
{
SheetName = "Data",
Headers = new() { "ID", "Name" },
Rows = new() { new Cell[] { Cell.FromNumber(1), Cell.FromText("Alice") } },
});
// 追加的表头含新列 Price → 合并为 ID | Name | Price;数据行按列名对齐
Excel.Append("align.xlsx", new SheetData
{
SheetName = "Data",
Headers = new() { "ID", "Price" },
Rows = new() { new Cell[] { Cell.FromNumber(2), Cell.FromNumber(9.5) } },
});
var sheet = XlsxReader.Read("align.xlsx", 0); // 低层读回(见附录 B.2)
Console.WriteLine("headers: " + string.Join(" | ", sheet.Headers));
var ws2 = Excel.Open("align.xlsx").Worksheets["Data"];
Console.WriteLine($"C3 = {ws2.Cell("C3").Number}"); // Price 对齐到第 3 列
Console.WriteLine($"B3 类型 = {ws2.Cell("B3").Type}"); // 缺失列补 Empty
输出:
21.4 流式写入 CreateWriter¶
Excel.CreateWriter 返回 XlsxStreamWriter(见附录 B.5),逐行写大文件,不驻留内存。仅支持 .xlsx / .xlsm 扩展名;使用后必须 Dispose / Close 完成文件:
using var writer = Excel.CreateWriter("big_out.xlsx");
for (int i = 0; i < 1_000_000; i++)
writer.WriteRow(new object?[] { i, $"row {i}", i * 1.5, i % 2 == 0 });
// using 结束自动 Close
输出:
也可写入流(LeaveOpen 由调用方管理):
using var ms = new MemoryStream();
using (var writer = Excel.CreateWriter(ms))
writer.WriteRow(new object?[] { 1, "a" });
ms.Position = 0;
var read = XlsxReader.Read(ms, 0);
XlsxStreamWriter 支持样式 / 公式 / 超链接随行写入(styles.xml 与 sheet rels 在 Close 时统一写出);合并 / 筛选 / 图片等高级能力不支持。超链接数量极大时内存不再恒定(内部缓冲全部超链接引用)。
单表行数上限:Excel 每张工作表最多 1,048,576 行。达到上限时的行为由 RowLimitExceededMode 决定:
Throw(默认):抛RowLimitExceededException(继承LiteExcelException),文件保持有效SpillToNewSheet:自动新建工作表(Sheet1/Sheet2/ ...)继续写入Truncate:停止写入后续行,文件以满行为止;通过writer.Truncated查询是否发生了截断
// 默认抛异常
using var w1 = Excel.CreateWriter("a.xlsx");
// 自动分表
using var w2 = Excel.CreateWriter("b.xlsx", RowLimitExceededMode.SpillToNewSheet);
// 截断
using var w3 = Excel.CreateWriter("c.xlsx", RowLimitExceededMode.Truncate);
for (int i = 0; i < 3_000_000; i++) w3.WriteRow(new object?[] { i });
// w3.Truncated == true(超出 1,048,576 的部分被丢弃)
分表时可指定表头,让每张表首行一致:
using var writer = Excel.CreateWriter("big_out.xlsx", RowLimitExceededMode.SpillToNewSheet,
spillHeader: new object?[] { "ID", "名称", "值" });
for (int i = 0; i < 3_000_000; i++)
writer.WriteRow(new object?[] { i, "row" + i, i * 1.5 });
// 3 个表,每表首行都是 ID/名称/值,调用方只写数据行
spillHeader 仅在 SpillToNewSheet 模式下生效;其他模式忽略。
21.5 大文件与内存模型¶
大文件场景优先用流式入口,避免整体加载到内存:
using LiteExcel;
using (var writer = Excel.CreateWriter("big.xlsx"))
{
writer.WriteRow(new[] { Cell.FromText("序号"), Cell.FromText("值") });
for (int i = 1; i <= 100000; i++)
writer.WriteRow(new[] { Cell.FromNumber(i), Cell.FromNumber(i * 1.5) });
}
long rows = 0;
Excel.StreamRows("big.xlsx", "Sheet1", row => rows++);
Console.WriteLine($"共 {rows} 行");
Excel.ReadWithProgress("big.xlsx", 0, (current, total) =>
Console.WriteLine($"进度 {current}/{total}"));
- 内存模型:
Excel.Open/Excel.Create返回的Workbook是内存模型,整簿加载到内存。超大文件请用流式 API 而非Excel.Open。 - 流式写入范围:
Excel.CreateWriter/Excel.Append仅支持 xlsx / xlsm。 - 统一读取门面:
Excel.Read<T>、Excel.ReadSheet、Excel.ReadAsDataTable、Excel.StreamRows和Excel.EnumerateRows支持按路径自动路由 xlsx/xlsm/xlsb/xls;从流读取时须显式传入ExcelFormat。 - 四格式流式读取:xlsx/xlsm、xlsb、xls 均支持逐行读取并提前终止(
Take(n)/First()/break),不驻留完整行数据。共享字符串与样式表仍预加载(工作簿级共享)。 - 超链接数量:流式写入器在超链接数量极大时内存不再恒定(内部缓冲全部超链接引用)。
- 追加:
Excel.Append会读取整个既有文件再写出,适合中小文件增量追加。
21.6 拉取式枚举 EnumerateRows¶
Excel.EnumerateRows 返回 IEnumerable<IReadOnlyList<Cell>>,逐行延迟产出,支持 LINQ 与提前中断,不驻留内存。
与 StreamRows(§21.1)的对照:
StreamRows |
EnumerateRows |
|
|---|---|---|
| 模型 | 推送(Action 回调) |
拉取(IEnumerable) |
| 首行 | 自动跳过 | 不跳过,返回全部原始行 |
| 提前中断 | 不支持 | 支持(break / First() / Take(n)) |
| LINQ | 不支持 | 支持 |
// 只要第一行(读到第一行即停,不扫完整表)
var first = Excel.EnumerateRows("big.xlsx", "Sheet1").First();
// 前 100 行
foreach (var row in Excel.EnumerateRows("big.xlsx", "Sheet1").Take(100))
Console.WriteLine(row[0].GetString());
// 跳过表头
foreach (var row in Excel.EnumerateRows("big.xlsx", "Sheet1").Skip(1))
Process(row);
// 不传表名 → 取第一张表
foreach (var row in Excel.EnumerateRows("big.xlsx"))
Process(row);
sheetName 为 null 时取第一张表。仅支持 xlsx / xlsm。迭代器释放时关闭文件句柄,break 提前退出也会释放。