附录 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) |