跳转至

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();
});

输出:

Alice | 95 |
Bob | 88 |

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}"));

输出:

1/3
2/3
3/3

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);

输出:

5

追加不改变既有 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

输出:

headers: ID | Name | Price
C3 = 9.5
B3 类型 = 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

输出:

已写入 big_out.xlsx

也可写入流(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 提前退出也会释放。

// WinForms 异步调用,避免 UI 线程卡死
var names = await Task.Run(() => Excel.GetSheetNames(sPath));
await Task.Run(() =>
{
    foreach (var row in Excel.EnumerateRows(sPath, names[0]))
        Handle(row);
});