技術文章

在 Delphi 中做到不失真的 XLSX 往返

帳務作業開啟客戶範本、把 42750 寫進 B3、然後存檔。事後把兩個解開的套件拿來比對,變更清單遠不止一個儲存格: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 檔是一包 XML 部件組成的 ZIP:xl/workbook.xml、每張工作表一個 xl/worksheets/sheetN.xml、xl/styles.xml、xl/sharedStrings.xml,加上佈景主題、計算鏈,以及活頁簿帶著的繪圖、表格與樞紐分析快取。把值與公式讀進物件、存檔時再從這些物件重新產生每個部件的程式庫,有一個共同的弱點:物件模型沒有槽位的東西進不了記憶體,重新產生的部件自然少了它。沒有人需要去刪走勢線;它們只是在 Open 與 SaveAs 之間根本無處容身

ECMA-376 早料到一半。SpreadsheetML 保留 extLst(ECMA-376 Part 1 §18.2.10 是活頁簿層級元素,工作表、樣式與條件式格式也各有對應元素)作為未來功能的存放區。較新的生產端把每項功能包進一個以 uri 屬性指名功能的 <ext> 元素,並預期較舊的消費端把它看不懂的東西原樣帶著。走勢線、交叉分析篩選器清單、較新的資料橫條與圖示集選項、擴充的資料驗證,在現今 Excel 寫出的檔案裡都走這條路。因此丟掉看不懂的 <ext> 區塊,破壞的正是這個格式賴以運作的前向相容契約,而且損害要到客戶在 Excel 裡重新開檔才會浮現

佈景主題與計算鏈出問題的原因不同,各自需要一套處理。本文其餘部分會走過 HotXLS 如何處理這三者、Delphi 呼叫端能觀察與檢查什麼,以及保證到哪裡為止

在 Delphi 中保住自訂的 theme1.xml

HotXLS 保存活頁簿佈景主題的方式,是握住開檔時 xl/theme/theme1.xml 的原始位元組,並在 SaveAs 時把這個部件原樣寫回。佈景主題部件(ECMA-376 Part 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 佈景主題。自帶佈景主題的活頁簿,快取部件說了算,這兩個 setter 動不了存出的檔案。色彩的處理不同: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 資料驗證擴充讀進資料驗證集合,交叉分析篩選器清單由篩選器模型重新輸出。其餘全部落在每個 TXLSXWorksheet 的唯讀字串清單 RawWorksheetExts 裡,一個區塊一條 XML 片段,測試因此能確切檢查哪些東西會被帶到未來

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> 元素上,片段因此自給自足;但區塊也可能倚賴 x14ac 或 xr 這種只在來源 <worksheet> 根上宣告過一次的字首。把這種片段重播進沒有該宣告的工作表,存出的 XML 就不是命名空間完備的。HotXLS 會掃描每個擷取片段用了卻沒宣告的字首,把來源上對應的宣告記進 RawExtNamespaceDecls,並寫到輸出工作表的根上。片段既然只是純字串,在活頁簿內或跨活頁簿複製工作表時也能把它們一併帶到新的工作表

把 calcChain.xml 寫成 Excel 信任的樣子

只要存出的活頁簿含至少一個公式儲存格,HotXLS 就寫 xl/calcChain.xml(Calculation Chain 部件,ECMA-376 Part 1 §12.3.1),連同它的 content-type 覆寫與活頁簿關聯。每個項目是一個 <c r="D10" i="1"/> 元素:儲存格參照加上 1 起算的工作表索引;規格其實允許同一張工作表連續項目省略索引,寫入端在每個項目上都寫。明確寫出比較簡單,也一樣合法

順序取決於活頁簿已經知道什麼。公式相依圖存在且是最新的——也就是剛 Recalculate 過的狀態——時,鏈走完整的拓撲序:每個公式排在其依賴的儲存格之後,循環參考的成員附加在結尾,鏈仍然列出每一個公式儲存格。圖過期或從未建立時,公式儲存格按文件順序、逐張工作表列出。兩種都合法。Microsoft 的格式實作筆記 [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。來自冷門增益集、既不受建模也不落在擴充點裡的部件,就在本文三道機制之外

真正要緊的檢查用的是你自己的檔案。開一份功能豐富的正式範本、改一個值、存檔、解開兩個套件、逐個部件 diff。預期差異會出現在你編輯的那張工作表、styles.xml 與 extLst 內部的屬性格式;佈景主題部件應與輸入一致,<ext> 元素應列出相同的 uri 值,calcChain.xml 應點名每一個公式儲存格。超出這份清單的差異,都值得在範本進正式環境前追一遍

佈景主題保留、外來 extLst 重播與計算鏈輸出都是 HotXLS Delphi Excel Component XLSX 引擎的一部分;產品頁列有它為 Delphi 與 C++Builder 專案讀寫的其餘內容