跳转至

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

输出:

[降级] Comments -> Csv @ Sheet1: CSV 不支持批注,工作表 'Sheet1' 的批注已丢弃。

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

输出:

Sheet1: hello

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

输出:

Name: Score
Alice: 95
Bob: 88

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

输出:

无法写出 Csv:Csv 格式不支持文件级密码(打开密码/修改密码)。请使用 xlsx/xlsm/xlsb 保存,或先移除密码。

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

输出:

已写入 macro_copy.xlsm