20. 多格式行为¶
本章列出各格式的能力支持情况、降级行为,以及 CSV / 加密的格式限制。
20.1 格式能力矩阵¶
下表列出每个能力在各格式下的支持情况;其中 xls / xlsb / csv 不支持的能力在写出时经 ExcelWriteOptions.OnDegradation 上报(见第 22 章)。
| 能力 | xlsx | xlsm | xlsb | xls | csv |
|---|---|---|---|---|---|
| 单元格值 / 表头 | ☑️ | ☑️ | ☑️ | ☑️ | 仅文本 |
| 样式(字体 / 颜色 / 边框 / 对齐 / 换行) | ☑️ | ☑️ | 仅数字格式 | 仅数字格式 | ❌ |
| 数字格式 | ☑️ | ☑️ | ☑️ | ☑️ | ❌ |
| 合并单元格 | ☑️ | ☑️ | ☑️ | ☑️ | ❌ |
| 自动筛选 | ☑️ | ☑️ | 范围读写 | ❌ | ❌ |
| 行高 / 列宽 | ☑️ | ☑️ | ☑️ | ☑️ | ❌ |
| 批注 | ☑️ | ☑️ | ☑️ | ☑️ | ❌ |
| 数据验证 | ☑️ | ☑️ | ☑️ | ❌ | ❌ |
| 超链接 | ☑️ | ☑️ | ☑️ | ☑️ | ❌ |
| 冻结窗格 | ☑️ | ☑️ | ☑️ | ☑️ | ❌ |
| 图片(浮动 / 单元格内嵌) | ☑️ | ☑️ | 浮动写入 | ❌ | ❌ |
| 条件格式 | ☑️ | ☑️ | 全类型写入 | ❌ | ❌ |
| 超级表 | ☑️ | ☑️ | ☑️ | ❌ | ❌ |
| 命名区域 | ☑️ | ☑️ | 仅读取 | 仅读取 | ❌ |
| 工作表可见性(隐藏/深度隐藏) | ☑️ | ☑️ | ☑️ | ☑️ | ❌ |
| 工作表标签颜色 | ☑️ | ☑️ | ❌ | ❌ | ❌ |
| 文档属性 | ☑️ | ☑️ | ☑️ | ❌ | ❌ |
| 打开 / 修改密码 | ☑️ | ☑️ | ☑️ | ❌ | ❌ |
| 插入 / 删除行列 | ☑️ | ☑️ | ☑️ | ☑️ | ❌ |
| 公式(写) | ☑️ | ☑️ | 基础写回 | 基础写回 | ❌ |
| 公式(读) | ☑️ | ☑️ | 可解析时还原 | 可解析时还原 | ❌ |
| 图表 / 透视表 | 只保真 | 只保真 | 只保真 | ❌ | ❌ |
| 流式读(StreamRows / EnumerateRows) | ☑️ | ☑️ | ☑️ | ☑️ | ❌ |
| 流式写(XlsxStreamWriter) | ☑️ | ☑️ | ❌ | ❌ | ❌ |
| 追加(Append) | ☑️ | ☑️ | ❌ | ❌ | ❌ |
| 进度回调(ReadWithProgress) | ☑️ | ☑️ | ❌ | ❌ | ❌ |
| CSV 分隔符(读自动探测 / 写指定) | n/a | n/a | n/a | n/a | ☑️ |
| 降级上报(OnDegradation) | n/a | n/a | ☑️ | ☑️ | ☑️ |
| 自动列宽(AutoFitColumns / AutoColumnWidths) | ☑️ | ☑️ | ☑️ | ☑️ | ❌ |
| 图例:☑️ 支持 · ❌ 不支持 · 单元格内文字表示部分支持 |
跨格式转换:打开 .xlsb 后另存为 .xlsx / .xlsm 时,透视表、切片器、数据查询(Power Query)、数据模型、图形等高级内容也会一并保留(见 §20.5)。
写出到 csv 时接通降级回调,观察被丢弃的能力:
var wb = Excel.Create();
var ws = wb.Worksheets["Sheet1"];
ws.SetValue("A1", "x");
ws.Comments = new Dictionary<string, string> { { "A1", "note" } };
Excel.Write("matrix.csv", wb, new ExcelWriteOptions
{
OnDegradation = info =>
Console.WriteLine($"[降级] {info.Capability} -> {info.TargetFormat} @ {info.SheetName}: {info.Message}"),
});
输出:
20.2 xls / xlsb 的读写降级¶
xls / xlsb 写出时按格式与路径区分:
- xlsb 重建写出(新建 / 编辑单元格后保存):样式降级为仅保留
NumberFormat;批注 / 数据验证 / 超级表 / 浮动图片已支持写出;条件格式支持全部 18 种 OOXML 规则类型(cellIs / expression / colorScale / dataBar / iconSet / top10 / aboveAverage / belowAverage / 文本类 / 空值类 / 错误类 / uniqueValues / duplicateValues / timePeriod / textLength);命名区域仅读回、不写出;InCell 图片被丢弃;公式文本不保留,按缓存值写出。丢弃项经OnDegradation显式上报(见第 22 章)。 - xlsb 打开-保存 / 删表:未改动的内容原样保留,条件格式 / 图片 / 透视表 / 图表 / 切片器等完整保留,无降级上报。
- xls 写出:样式降级为仅保留
NumberFormat;批注支持写出;数据验证 / 超级表 / 条件格式 / 图片 / 命名区域被丢弃;公式文本不保留,按缓存值写出。这些降级经OnDegradation显式上报(见第 22 章)。
xls 工作表尺寸上限:
xls(BIFF8)最多 256 列 / 65536 行。超出上限的数据(含远超数据范围的列宽声明)在写出时被裁剪,经DegradationCapability.SheetSize上报。
xls / xlsb 读回时:样式仅保留 NumberFormat;xlsb 读回批注 / 数据验证 / 超级表 / 命名区域,xls 读回批注;条件格式 / 图片不读回;可解析的公式会还原为 A1 文本填入 Cell.Formula(数组公式 / 3D 引用 / 名称等无法解析时仅保留缓存值)。
读取 xls 文件(样式仅保留数字格式):
var wb = Excel.Create();
wb.Worksheets["Sheet1"].SetValue("A1", "hello");
Excel.Write("roundtrip.xls", wb);
var reopened = Excel.Open("roundtrip.xls");
var ws = reopened.Worksheets["Sheet1"];
Console.WriteLine($"{ws.Name}: {ws.Cell("A1").GetString()}");
输出:
20.3 CSV 行为¶
- CSV 仅支持单工作表工作簿(写出多表抛
NotSupportedException)。 - 读取时首行不拆分为表头(
CsvBackend.Read(见附录 B.4)返回原始行)。 - 分隔符:读取自动探测(逗号 > 分号 > Tab,仅统计引号外),
ExcelReadOptions.Separator可固定;写出默认逗号,ExcelWriteOptions.Separator可指定。 - 编码:读取默认按 BOM 探测并回退 UTF-8,写出默认 UTF-8 带 BOM。
ExcelReadOptions.Encoding/ExcelWriteOptions.Encoding可指定任意System.Text.Encoding实例(见下)。 - CSV 不支持样式 / 合并 / 批注 / 数据验证 / 超链接 / 图片 / 条件格式 / 超级表 / 命名区域 / 文档属性 / 公式 / 密码。
编码选项:编码实例由调用方提供,本库不引用任何编码包。
// 默认:写出 UTF-8 带 BOM(Excel 打开中文不乱码),读取按 BOM 探测
Excel.Write("out.csv", wb);
var back = Excel.Open("out.csv");
// 指定编码(BOM 由该编码的 preamble 决定)
Excel.Write("out.csv", wb, new ExcelWriteOptions { Encoding = new UTF8Encoding(false) }); // 不写 BOM
Excel.Write("gbk.csv", wb, new ExcelWriteOptions { Encoding = Encoding.GetEncoding(936) }); // GBK
var gbk = Excel.Open("gbk.csv", new ExcelReadOptions { Encoding = Encoding.GetEncoding(936) });
Warning
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance)(需引用 System.Text.Encoding.CodePages)。
这是调用方的依赖决策,本库保持零第三方依赖。
显式指定 Encoding 时优先于文件 BOM;未指定时 BOM 优先。
写入再读回(读回时首行作为数据行,不拆分为表头):
var sheet = new SheetData
{
SheetName = "People",
Headers = new() { "Name", "Score" },
Rows = new()
{
new Cell[] { Cell.FromText("Alice"), Cell.FromNumber(95) },
new Cell[] { Cell.FromText("Bob"), Cell.FromNumber(88) },
},
};
Excel.Write("people.csv", sheet);
var wb = Excel.Open("people.csv");
var csv = wb.Worksheets[0].ToSheetData();
for (int r = 0; r < csv.Rows.Count; r++)
Console.WriteLine($"{csv.Rows[r][0].GetString()}: {csv.Rows[r][1].GetString()}");
输出:
20.4 加密文件格式限制¶
文件级密码(打开 / 修改)仅支持 xlsx / xlsm / xlsb;保存为 csv / xls 时若带密码会抛 LiteExcelException:
var wb = Excel.Create();
wb.Security.SetOpenPassword("1");
try
{
wb.SaveAs("enc.csv", ExcelFormat.Csv);
}
catch (LiteExcelException ex)
{
Console.WriteLine(ex.Message);
}
输出:
20.5 打开-保存保真¶
打开已有文件再保存时,未改动的内容会被原样保留,不会因为库不认识它而丢失。这包括宏、图表、透视表、透视缓存、超级表、切片器、外部连接、数据模型、自定义 XML、工作表标签颜色、样式等高级内容。改表名不再丢图表关联;追加数据不再丢宏。
删除工作表后保存也走同一套保真逻辑:被删表及其引用被摘除,其余内容完整保留,结果与 Excel 自身「删除工作表后另存」等价(xlsb 同样完整保留透视表 / 连接 / 数据模型 / VBA / 标签颜色)。
跨格式转换:打开 .xlsb 文件后另存为 .xlsx 或 .xlsm 时,除了普通数据和样式,透视表、透视缓存、切片器、数据查询(Power Query)、数据模型、图形(含 ActiveX 形状)、条件格式等也会尽量保留,在 Excel 中可正常打开。若需要回到旧行为(丢弃这些内容并记录提示),可设置环境变量 LITEXCEL_DISABLE_PIVOT_WIRING=1。
⚠️ 例外(含 Power Query / 数据模型的 xlsb):在包含 Power Query 或数据模型的 .xlsb 文件中,删除工作表、插入/删除行列、修改工作表可见性或标签颜色、增删超级表等操作之后另存,生成的文件可能无法被 Excel 打开。修改单元格内容、重命名工作表、在末尾追加普通工作表不受影响。详见 §7.6 删除整张工作表 的已知限制说明。
保真不只是留下内容本身,这些内容之间的关联也会一并保留,Excel 打开时不会出现丢失或错乱。
XLS 透视表降级:源 .xls 文件包含透视表时,当前无法保真写回或转换,透视表会被丢弃并记录到
wb.SaveDegradations(默认放行);设wb.AllowFeatureLossOnSave = false可改为抛LiteExcelException阻止。
var wb = Excel.Open("macro.xlsm"); // 打开包含宏的 xlsm
wb.Worksheets[0].Name = "重命名表"; // 改表名不丢 drawing 关联
wb.SaveAs("macro_copy.xlsm");
输出: