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}");
},
});
输出:
DegradationCapability 枚举列出所有可被降级上报的能力:
输出:
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}");
},
});
输出:
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}"),
});
输出: