跳转至

22. 降级回调 OnDegradation

本章介绍能力降级:写出到不支持某能力的格式时,对被丢弃的能力逐项记录与上报。

默认放行 + 非静默:Workbook.AllowFeatureLossOnSave 默认 true。目标格式不支持的能力(VBA 宏 / BIFF8 透视表 / XLSB 高级部件等)默认放行保存,不再抛异常阻止;每次 Save/SaveAs 的丢弃项会累积到只读清单 Workbook.SaveDegradations(IReadOnlyList<DegradationInfo>,每次保存前清空),可随时查询"这次保存丢了什么"。设 AllowFeatureLossOnSave = false 恢复严格模式(抛 LiteExcelException 阻止保存)。

var wb = Excel.Open("data.xlsb");
wb.SaveAs("data.xlsx");                 // 默认放行;含宏时剥离 VBA
foreach (var d in wb.SaveDegradations)  // 查询本次保存丢弃的能力
    Console.WriteLine($"{d.Capability}: {d.Message}");
// 输出示例:Macros: 源工作簿包含 VBA 宏,而 Xlsx 格式不支持宏,宏代码将被剥离。…

wb.AllowFeatureLossOnSave = false;      // 严格模式:不支持的格式将抛异常

22.1 能力枚举 DegradationCapability

ExcelWriteOptions.OnDegradation 为可选回调(Excel.Write 路径;wb.SaveAs 路径用 wb.SaveDegradations 查询)。写出到不支持某能力的格式(xls / xlsb / csv)时,对被丢弃的能力逐项回调:

var wb = Excel.Create();
var ws = wb.Worksheets["Sheet1"];
ws.SetValue("A1", "x");
ws.Comments = new Dictionary<string, string> { { "A1", "note" } };   // csv 不支持批注

Excel.Write("out.csv", wb, new ExcelWriteOptions
{
    OnDegradation = info =>
    {
        Console.WriteLine($"[降级] {info.Capability} -> {info.TargetFormat} @ {info.SheetName}: {info.Message}");
    },
});

输出:

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

DegradationCapability 枚举列出所有可被降级上报的能力:

foreach (var cap in Enum.GetNames(typeof(DegradationCapability)))
    Console.WriteLine(cap);

输出:

Comments
DataValidation
AutoFilter
Images
DocumentProperties
NamedRanges
Styles
MergedCells
FreezePanes
Hyperlinks
RowHeights
ColumnWidths
Formulas
Charts
PivotTables
RichData
ConditionalFormatting
Tables
Macros
SheetSize
SheetVisibility

22.2 降级信息 DegradationInfo

DegradationInfo 携带单次降级事件的完整描述:Capability(被丢弃能力)、SheetName(工作簿级能力为 null)、TargetFormat(目标格式)、Message(人类可读说明)。

var wb = Excel.Create();
var ws = wb.Worksheets["Sheet1"];
ws.SetValue("A1", "x");
ws.Comments = new Dictionary<string, string> { { "A1", "note" } };

Excel.Write("deg.csv", wb, new ExcelWriteOptions
{
    OnDegradation = info =>
    {
        Console.WriteLine($"Capability={info.Capability}");
        Console.WriteLine($"SheetName={info.SheetName}");
        Console.WriteLine($"TargetFormat={info.TargetFormat}");
        Console.WriteLine($"Message={info.Message}");
    },
});

输出:

Capability=Comments
SheetName=Sheet1
TargetFormat=Csv
Message=CSV 不支持批注,工作表 'Sheet1' 的批注已丢弃。

22.3 样式降级细节

xls / xlsb 写出时,完整样式(字体 / 颜色 / 边框 / 对齐 / 换行)降级为仅保留 NumberFormat,经 DegradationCapability.Styles 上报:

var wb = Excel.Create();
var ws = wb.Worksheets["Sheet1"];
ws.SetValue("A1", 1);
ws.Cell("A1").Style = new CellStyle { Bold = true, FillColor = "FFFF00" };

Excel.Write("style.xls", wb, new ExcelWriteOptions
{
    OnDegradation = info => Console.WriteLine($"{info.Capability}: {info.Message}"),
});

输出:

Styles: xls 仅支持数字格式,工作表 'Sheet1' 的完整样式(字体/颜色/边框/对齐/换行)已降级。