跳转至

附录 B 低层 API 参考

适用场景:适合自定义 / 裸行数据 / 大文件场景。日常用法优先用对象模型 API(第 2-25 章)。低层 API 的坐标约定:SheetData.Rows 的 Cell 是 0-based 网格,Headers 为首行表头文本。


B.1 SheetData

↳ 正文:第 5 章 数据类型与转换(List\<T> / DataTable 映射底层即 SheetData)、第 21 章 流式读取 / 进度回调 / 追加数据(流式 / 追加的数据载体)

public sealed class SheetData
{
    public string SheetName { get; set; } = "Sheet1";
    public List<string> Headers { get; set; } = new();
    public List<IReadOnlyList<Cell>> Rows { get; set; } = new();
    public List<CellRange> MergedRanges { get; set; } = new();
    public AutoFilter? Filter { get; set; }
    public bool FreezeHeader { get; set; }
    public int FreezeRows { get; set; }
    public int FreezeColumns { get; set; }
    public List<double>? ColumnWidths { get; set; }
    public CellStyle? HeaderStyle { get; set; }
    public CellStyle? DefaultStyle { get; set; }
    public Dictionary<int, CellStyle>? RowStyles { get; set; }
    public Dictionary<int, CellStyle>? ColumnStyles { get; set; }
    public Dictionary<int, double>? RowHeights { get; set; }
    public Dictionary<string, string>? Comments { get; set; }
    public List<DataValidation>? Validations { get; set; }
    public List<ConditionalFormat> ConditionalFormats { get; set; } = new();
    public string? CodeName { get; set; }
    public List<WorksheetImage>? Images { get; set; }
    public SheetProtection? Protection { get; set; }
    public List<XlTable> Tables { get; set; } = new();
}

B.2 XlsxReader

↳ 正文:第 3 章 文件导航:打开 / 创建 / 保存 / 格式(打开 / 流读取的低层入口)、第 21 章 流式读取 / 进度回调 / 追加数据(21.4 流式读回)

成员 说明
Read(path, sheetIndex[, firstRowIsHeader]) 按索引读单表
Read(path, sheetName[, firstRowIsHeader]) 按名称读单表
Read(stream, sheetIndex/name[, firstRowIsHeader]) 从流读单表
ReadAll(path) / ReadAll(stream) 读所有表
Read<T>(path, sheetIndex/name[, configure]) 读为 List\<T>
ReadAsDataTable(path, sheetIndex/name[, firstRowIsHeader]) 读为 DataTable
GetSheetNames(path) / GetSheetNames(stream) 列出工作表名
StreamRows(path/stream, sheetName, onRow) 流式逐行读取
ReadWithProgress(path, sheetIndex, onProgress) 带进度读取
ReadProperties(path) / ReadProperties(stream) 读取文档属性

B.3 XlsxWriter

↳ 正文:第 3 章 文件导航:打开 / 创建 / 保存 / 格式(Excel.Write 写出)、第 21 章 流式读取 / 进度回调 / 追加数据(21.3 Append 的低层写出)

成员 说明
Write(path, SheetData[, properties]) 写单表
Write(path, IReadOnlyList<SheetData>[, properties]) 写多表
Write(stream, SheetData[, properties]) 写单表到流
Write(stream, IReadOnlyList<SheetData>[, properties]) 写多表到流
Write<T>(path, data[, configure]) 写 List\<T>
Write(path, DataTable[, sheetName]) 写 DataTable
Append(path, SheetData[, properties]) 追加数据
AutoColumnWidths(SheetData) 列宽自适应

注意:XlsxWriter.Write 对 .xlsm 扩展名自动写出 macroEnabled 主文档类型;SheetData 写出时校验表名(InvalidSheetNameException)与重复表名(LiteExcelException)。

B.4 CsvBackend

↳ 正文:第 20 章 多格式行为(20.3 CSV 行为)

低层 CSV 后端为 internal,日常 CSV 读写请走 Excel.Open / Excel.Write。此处列出行为要点供参考。

  • 实现 RFC 4180 基础子集:双引号包裹含分隔符 / 换行 / 引号的字段。
  • 读取分隔符自动探测(逗号 > 分号 > Tab,仅统计引号外);ExcelReadOptions.Separator 可固定。
  • 写出默认逗号,ExcelWriteOptions.Separator 可指定。
  • 仅表格数据,不支持样式 / 合并 / 批注等 Excel 专有能力。

B.5 XlsxStreamWriter

↳ 正文:第 21 章 流式读取 / 进度回调 / 追加数据(21.4 流式写入 CreateWriter)

适合大文件逐行写入。通过 Excel.CreateWriter(path|stream) 获取。

成员 说明
Create(path) / Create(stream) 创建写入器
WriteRow(IEnumerable<object?>) 写一行值
WriteRow(IEnumerable<Cell>) 写一行 Cell
Close() / Dispose() 完成文件(必须调用)
  • 采用内联字符串(inlineStr),避免共享字符串表预扫描。
  • 支持单工作表;样式 / 公式 / 超链接随行写入(styles.xml 与 sheet rels 在 Close 时统一写出)。
  • 合并 / 筛选 / 图片等高级能力不支持。
  • 超链接数量极大时内存不再恒定。

B.6 CellRef

↳ 正文:第 4 章 单元格与取值(A1 地址访问单元格)

成员 说明
Parse(cellRef) "A1" -> (row=0, col=0)
TryParse(cellRef, out pos) 尝试解析
ParseRange(range) 解析区域引用(0-based 含端点)
ToString(row, col) (0,0) -> "A1"
ColToLetter(col) 0 -> "A"
LetterToCol(letters) "A" -> 0

B.7 新旧 API 对照

对象模型 API 与低层 API 等价关系速查(对象模型按扩展名自动路由格式;低层 API 仅处理 xlsx/xlsm):

场景 对象模型 API 低层 API
打开文件 Excel.Open(path[, options]) XlsxReader.Read(path, 0)(单表)/ XlsxReader.ReadAll(path)(全部表)
新建并写出 Excel.Create(...) + wb.SaveAs(path) XlsxWriter.Write(path, sheet)
读单表 wb.Worksheets[i] / wb.Worksheets["name"] XlsxReader.Read(path, sheetIndex) / XlsxReader.Read(path, sheetName)
读 List\<T> Excel.Read<T>(path[, sheetName, configure]) XlsxReader.Read<T>(path, 0[, configure])
读 DataTable Excel.ReadAsDataTable(path[, sheetName]) XlsxReader.ReadAsDataTable(path, 0)
写 List\<T> Excel.Write(path, list[, sheetName, configure]) XlsxWriter.Write(path, list)
写 DataTable Excel.Write(path, table[, sheetName]) XlsxWriter.Write(path, table, sheetName)
流式读 Excel.StreamRows(path, sheetName, onRow) XlsxReader.StreamRows(path, sheetName, onRow)
流式写 Excel.CreateWriter(path) XlsxStreamWriter.Create(path)
追加 Excel.Append(path, SheetData[, properties]) XlsxWriter.Append(path, SheetData[, properties])
列名 Excel.GetSheetNames(path) XlsxReader.GetSheetNames(path)