技术文章

Delphi 中的 XLSX 无损往返:主题、extLst 与 calcChain

一个计费作业打开客户模板,往 B3 写入 42750,然后保存。事后解压两个包做差异比对,变更清单远不止一个单元格:xl/theme/theme1.xml 里客户的青绿与石板灰换成了 Office 出厂配色,工作表 XML 底部的 <extLst> 丢了迷你图组和一条较新的条件格式规则,而 xl/calcChain.xml 干脆不见了。Excel 打开文件,提示修复,品牌配色已无影无踪。代码只碰了一个单元格。其余一切都变了,因为保存是按内存模型所知道的那点东西重建整个包的,而典型模板里有三个部件本来就在电子表格模型的辖区之外

HotXLS 在 Delphi 中实现无损 XLSX 往返的三套机制:xl/theme/theme1.xml 作为原始字节缓存并原样写回、仅 ThemeColor 槽位覆盖处除外,外来 extLst 块从 XML 事件中捕获并重放,每次保存公式时都生成一份全新的符合规范的 calcChain.xml
每个被保住的部件在保存时都走自己的路径 —— 逐字节的主题字节、事件级的 extLst 重放、重新生成的计算链 —— 而工作表 XML 和样式则由模型重建

为什么改一个单元格会重写整个 XLSX 包

.xlsx 文件是一包打成 ZIP 的 XML 部件:xl/workbook.xml、每张表一份的 xl/worksheets/sheetN.xml、xl/styles.xml、xl/sharedStrings.xml,加上主题、计算链,以及工作簿携带的所有绘图、表格和透视缓存。把值和公式读进对象、保存时再从这些对象重新生成每个部件的库,有一个天然弱点:对象模型没有槽位的东西根本进不了内存,重新生成的部件里自然也就没有它。迷你图不需要谁去删,只是在 Open 和 SaveAs 之间无处容身而已

ECMA-376 对其中一半早有预案。SpreadsheetML 把 extLst(ECMA-376 第 1 部分 §18.2.10 定义了工作簿级元素,工作表、样式和条件格式上也有对应元素)预留为未来功能存放区。较新的生成方把每个功能包进一个 <ext> 元素,用 uri 属性标明功能身份,而较老的消费方被期待把看不懂的东西原样带着走。迷你图、切片器列表、较新的数据条与图标集选项、扩展数据验证,在如今 Excel 写出的文件里都走这条路。所以丢弃未知 <ext> 块,破坏的正是这套格式赖以设计的向前兼容契约,而且损害要等客户在 Excel 里重新打开文件才会现形

主题和计算链失守的原因各不相同,所以各需各的对策。本文余下部分逐一拆解 HotXLS 如何处理这三者,Delphi 调用方能观察到、检验到什么,以及这份保证到哪里为止

在 Delphi 中让自定义 theme1.xml 原封不动

HotXLS 保住工作簿主题的方式,是握住打开包里 xl/theme/theme1.xml 的原始字节,在 SaveAs 时把这个部件原样写回。主题部件(ECMA-376 第 1 部分 §14.2.7)属于 DrawingML:一个带十二个槽位的配色方案、一个字体方案、一个由填充、线条和效果组成的格式方案。单元格样式用 <color theme="4"/> 之类的引用指进去,所以电子表格引擎只需要解析槽位,永远不需要理解渐变或效果样式。每次保存都重新生成一份固定 Office 主题,恰恰就是把客户的青绿染成 Office 蓝的那只手。从零新建、无主题可带的工作簿,则拿内置 Office 主题

HotXLS 在打开时缓存 xl/theme/theme1.xml 的原始字节,保存时原样写回,只替换经 ThemeColor 覆盖的颜色槽位,而按模型重建的库会重新生成一份出厂 Office 主题,把客户的品牌配色弹回去
逐字节缓存 theme1.xml 完全不需要主题模型,而 ThemeMajorFont 与 ThemeMinorFont 只对不带已捕获主题的工作簿起作用

日常场景根本不需要写任何主题代码。注意工作表索引:XLSX 引擎里 Sheets 从 1 数起,Cells[3, 2] 是第 3 行第 2 列,也就是 B3

var
  Book: TXLSXWorkbook;
begin
  Book := TXLSXWorkbook.Create;
  try
    Book.Open('branded-invoice.xlsx');
    Book.Sheets[1].Cells[3, 2].Value := 42750.00;  // 唯一的那处改动
    Book.SaveAs('branded-invoice-out.xlsx');
    // 输出里的 xl/theme/theme1.xml 带着模板自己的主题
  finally
    Book.Free;
  end;
end;

对这类部件,原始字节就是能拿到的最强保真:不解析、不重新序列化、没有任何可漂移之处。当保存输出的是 Strict OOXML 而非 transitional 方言时,捕获的主题会过一遍命名空间转换器而不是直接复制,因为逐字节复制会把 transitional 命名空间 URI 留在 Strict 包里

陷阱在 API 一侧。TXLSXWorkbook 暴露了 ThemeMajorFont 和 ThemeMinorFont,Open 之后它们报告从模板字体方案解析出的标题字体和正文字体。给它们赋值看上去正是换字体的正路,但它们只塑造新工作簿拿到的内置 Office 主题。在工作簿自带主题的场合,捕获的部件说了算,这两个设置器对保存出的文件毫无影响。颜色的处理则不同:ThemeColor[Slot] 寻址十二个 clrScheme 槽位,覆盖值会被写进被保留的主题——只替换该槽位的颜色,字体方案、格式方案和任何主题扩展都原封不动

Book.Open('branded-invoice.xlsx');
// 对保存出的文件无效:模板自带的主题被原样保留
Book.ThemeMajorFont := 'Segoe UI Semibold';
// 确实会写进文件:只有 theme1.xml 里的 accent1 槽位改变
Book.ThemeColor[xlsxThemeAccent1] := $FF0F7B6C;  // $AARRGGBB
Book.SaveAs('rebranded.xlsx');

这条分界是刻意为之。颜色覆盖是对单个元素的一次窄而明确的修改,设计师主题的其余部分得以原样保留。重写字体方案则会波及按文字系统逐项列出的字体清单,面向数据的 API 找不到表达它们的好办法。模板真要换字体,就到 Excel 里改好再发新模板;主题该握在品牌归属者手里

保存时未知的 extLst 块会怎样

HotXLS 会捕获每个它没有原生建模的工作表级 <ext> 块,并把它重放进保存后工作表的 extLst。它建模了的块则被解析成类型化对象再从中重建:迷你图组进入 SparklineGroups,x14 数据验证扩展读进数据验证集合,切片器列表由切片器模型重新发出。其余一切按一块一个 XML 片段,落进每张 TXLSXWorksheet 上只读的 RawWorksheetExts 字符串列表——这意味着测试可以确切检查哪些内容会被带向前

var
  Book: TXLSXWorkbook;
  Sheet: TXLSXWorksheet;
  i: Integer;
begin
  Book := TXLSXWorkbook.Create;
  try
    Book.Open('from-newer-excel.xlsx');
    Sheet := Book.Sheets[1];
    WriteLn(Format('%d foreign ext block(s), %d sparkline group(s)',
      [Sheet.RawWorksheetExts.Count, Sheet.SparklineGroups.Count]));
    for i := 0 to Sheet.RawWorksheetExts.Count - 1 do
      WriteLn(Copy(Sheet.RawWorksheetExts[i], 1, 100)); // 开标签能看到 uri
    // 片段从 <worksheet> 根元素借来的命名空间声明
    WriteLn(Sheet.RawExtNamespaceDecls);
  finally
    Book.Free;
  end;
end;

捕获从 XML 事件流做起,因为流式读取器只交出元素、文本和结束标签,不交出源里的字节偏移。每个未知子树都在事件流过时由这些事件重建。朴素的深度计数器在这里会翻车:它见起始标签加一、见结束标签减一,而 <x14:cfvo type="min"/> 这样的自闭合子元素只作为一个标记为空的起始事件到达,后面没有结束标签可等。把它当成打开的元素计数,计数器就永远回不到零,捕获会把工作表余下部分整个吞掉。HotXLS 的捕获循环只对非空起始标签加深深度,本身就是空的 <ext/> 则立即作为单行片段存下

从事件重建有一个看得见的副作用。属性的引号风格、元素之间的空白,以及 <a></a> 与 <a/> 之间的取舍,回来时都是规范化过的,所以片段与原件含义等价,但不是逐字节相同。Excel 解析的是 XML,不比较字节。不过按文本比对的 diff 工具会把这变化标出来,最好在有人把它当回归上报之前心里有数

命名空间是重放片段的第二个坑。Excel 通常把需要的前缀就声明在 <ext> 元素上,片段因此自包含,但块也可能依赖在源 <worksheet> 根上一次性声明的 x14ac 或 xr 之类前缀。把这样的片段重放进没有该声明的工作表,保存出的 XML 在命名空间上就不是良构的。HotXLS 会扫描每个捕获片段,找出它用到却未声明的前缀,把源里对应的声明记进 RawExtNamespaceDecls,并写到保存后的工作表根上。因为片段只是普通字符串,在工作簿内或跨工作簿复制工作表也能把它们一并带到新表

写好 calcChain.xml,让 Excel 信任你的公式

只要保存的工作簿含至少一个公式单元格,HotXLS 就写出 xl/calcChain.xml(计算链部件,ECMA-376 第 1 部分 §12.3.1),连同它的 content-type override 和工作簿 relationship。每个条目是一个 <c r="D10" i="1"/> 元素:单元格引用加从 1 数起的工作表索引,schema 本允许同一张表上连续条目省略它,但写出器每个条目都写。显式更简单,也同样合法

顺序取决于工作簿已经知道什么。当公式依赖图存在且最新——正是 Recalculate 刚跑完的状态——计算链按完整拓扑顺序输出:每个公式排在其依赖的单元格之后,循环引用的成员追加在末尾,链条照样列出每个公式单元格。图已过期或从未建立时,公式单元格按文档顺序逐表列出。两者都合法。微软的格式实现说明 [MS-XLSX] 把这条链描述成一个提示,Excel 计算时会校验并重排,所以任何顺序的完整列表都能干净加载

HotXLS 在 Recalculate 已建好依赖图时按拓扑顺序输出 xl/calcChain.xml,否则按文档顺序输出;Excel 把任一完整列表都当提示,加载时重排
两种排序都合法,因为 Excel 加载时会重新校验这条链,而 HotXLS 从不在 SaveAs 内部强行做完整的依赖图构建
Book.Open('model.xlsx');
Book.Sheets[1].Cells[10, 4].Formula := '=SUM(D2:D9)';
// 此时保存,公式单元格按文档顺序列出,因为改动
// 公式已使依赖图失效
Book.Recalculate;   // 重建依赖图并刷新缓存值
Book.SaveAs('model-out.xlsx');
// calcChain.xml 现在按依赖顺序:D10 排在 D2:D9 之后

SaveAs 不会自作主张建图。完整的依赖构建意味着解析每条公式里的每个引用,在大模型上这是实打实的工作量,只想写个文件的调用方从没点过这份活。如果输出里的缓存值对你要紧——下游系统不打开 Excel 就直接读的场景通常都要紧——那无论如何在保存前调一次 Recalculate;按依赖排序的链条顺手就带上了

为什么要输出一个 Excel 只当建议的部件?因为它的缺席太扎眼。修复启发式、第三方查看器和 diff 工具都默认含公式的工作簿带着计算链,没有这条链的包看起来就不像 Excel 自己产出的任何东西。写一条有效的链,让输出留在生态系统其余部分演练过的形状里,代价不过是对公式单元格多扫一遍

无损往返到哪里为止

HotXLS 不逐字节复制整个包,输出也不该按这个标准评判。工作表 XML、styles.xml、共享字符串和工作簿部件都由解析出的模型重新生成,内容忠实,但与输入不是二进制相同。光是 ZIP 本地头就带着全新时间戳。捕获的 <ext> 片段如前所述是规范化后回来的。ThemeMajorFont 和 ThemeMinorFont 进不了被保留的主题,ThemeColor 覆盖则逐槽位写入其中

这张保护网有确定的形状:引擎原生建模的功能,如迷你图和扩展数据验证,被解析并重写;工作表级的外来 <ext> 内容,被重放;主题部件,按捕获原样携带。VBA 工程和外部工作簿引用按同一套「不建模也照留」的思路挺过保存,见VBA 与外部链接保留的姊妹篇;docProps 里的文档属性有自己的读写 API。既没被建模、又不在扩展点内的冷门加载项部件,就落在这三套机制之外

真正要紧的检查用的是你自己的文件。打开一个功能丰富的生产模板,改一个值,保存,解压两个包,逐部件做差异比对。预期差异出现在你编辑的那张表、styles.xml 和 extLst 内部的属性格式上;主题部件应与输入一致,<ext> 元素应列出相同的 uri 值,calcChain.xml 应点名每个公式单元格。清单之外的任何差异,都值得在模板投产前追查清楚

主题保留、外来 extLst 重放和计算链输出,都是 HotXLS Delphi Excel Component 中 XLSX 引擎的一部分;产品页列有它面向 Delphi 与 C++Builder 工程的其余读写能力