HotXLS 文件

活頁簿基礎架構 API

這些公開成員支援檢查 I/O、實作序列化器或跨活頁簿協調計算的整合;活頁簿成員宣告在 lxHandleX,工作區圖形宣告在 lxDepGraph

一般應用程式應優先使用儲存格格式、SaveAs、Recalculate 與外部活頁簿工作區 API;樣式池註冊與圖形排程需要與程式庫序列化器及計算引擎相同的索引與生命週期慣例

I/O 觀察與復原

TXLSXWorkbook.OnReadCell 在 XLSX 剖析期間,為每個具體化的儲存格收到工作表索引、列、欄、已儲存值與公式,並帶可寫入的 Cancel 旗標;TXLSXWorkbook.OnWriteCell 在儲存格序列化前收到可寫入的輸出值加 Skip 與 Cancel 旗標,讓宿主可以轉換或省略輸出,而不必改用直接串流 API 取代活頁簿 API

兩個回呼都使用 1 為基底的工作表與儲存格座標,宣告型別為 TXLSXCellReadEvent 與 TXLSXCellWriteEvent;回呼在作用中的 I/O 操作內執行,請避免在回呼裡對同一活頁簿啟動另一個操作

TXLSXWorkbook.RecoveryMode 預設 False,讓受支援的工作表 XML 剖析失敗轉成警告診斷並繼續開啟,可能只留下部分復原的工作表內容;它不保證能從讀不了的 ZIP 套件復原,儲存前請先檢視診斷與復原的資料

TXLSXWorkbook.FireProgress 把階段、狀態、目前數量與總數分派給指定的進度處理常式,舊式處理常式收到工作通知,延伸處理常式收到所有狀態;延伸處理常式可以要求取消,但寫入結束通知無法反轉已提交的輸出

TXLSXWorkbook.AddDiagnostic 附加並回傳一個由活頁簿持有的診斷,記錄提供的代碼、嚴重度、操作、訊息、原生代碼、工作表內容與套件部分名稱,提供例外時複製其類別名稱,並觸發 OnDiagnostic;它不取得例外的擁有權,也不擲出該例外

function TXLSXWorkbook.AddDiagnostic(ACode: Integer;
  ASeverity: TXLSDiagnosticSeverity; AOperation: TXLSDiagnosticOperation;
  const AMessage: WideString; ANativeCode, ASheetIndex: Integer;
  const ASheetName, APartName: WideString;
  AException: Exception): TXLSDiagnostic;

輸出政策與已存套件檢視

TXLSXWorkbook.CSVEmitFormulas 預設 False,把公式儲存格的 CSV 輸出從公式結果切換成公式文字;結果輸出會嘗試公式評估,評估失敗時改用已儲存的儲存格文字或值;TXLSXWorkbook.CSVQuoteAllStrings 也預設 False,強制為文字欄位加引號,而數值、日期、布林、Null 與 Empty 維持一般加引號規則

TXLSXWorkbook.LastSaveUsedStreaming 回報最近一次準備好的儲存是否使用工作表串流;TXLSXWorkbook.LastSavePeakRowXmlChars 回報最大的緩衝列 XML 片段,TXLSXWorkbook.LastSaveBufferedWorksheetXmlChars 回報合計的緩衝工作表 XML,TXLSXWorkbook.LastSavePeakAuxiliaryXmlChars 回報最大的受追蹤輔助 XML 片段;這些是序列化器檢測得到的字元數,不是處理序總記憶體量測,ODS 輸出也不走 XLSX 工作表串流路徑

TXLSXWorkbook.TryCopyPreservedPart 嘗試把符合條件的保留來源部分,包括其壓縮表示,複製到呼叫端提供的目的地 TZipArchive,複製成功回傳 True,需要一般序列化時回傳 False;來源必須在檔案型開啟下持續可用,缺失或明確丟棄的部分無法複製

目的地封存由呼叫端持有,必須正常完成;壓縮複製的回復失敗仍可能擲出例外,這個輔助函式既不建構完整的活頁簿套件,也不更新其關聯或內容型別

加密與活頁簿中繼資料

TXLSXWorkbook.SaveAsEncryptedAgile 接受檔名與非空密碼,在記憶體中序列化 XLSX 套件並寫出 Agile 加密容器,成功回傳 1,回報失敗回傳 -1;選用的 VerifyEncryptedSave 會在寫出後重新開啟檢查,且這個方法需要同時容納未加密套件與其序列化位元組的記憶體

TXLSXWorkbook.VerifyEncryptedFile 在暫時活頁簿中用提供的檔案與密碼開啟,只在開啟成功時回傳 True,例外會轉成 False;它檢查的是可讀性,而不是逐格與目前活頁簿比對,對未加密的 XLSX 輸入則遵循一般 OpenEncrypted 行為

TXLSXWorkbook.DocSecurity 儲存延伸文件屬性位元欄:1 代表密碼保護、2 建議唯讀、4 強制唯讀、8 鎖定註解;這些中繼資料位元本身不會施加加密或存取限制

TXLSXWorkbook.DocPropsTouched 是文件屬性寫入器用來判斷受追蹤屬性是否已設定的唯讀旗標;Title 這類受追蹤屬性 setter 會設定它,直接指派的延伸中繼資料則不會自動設定

TXLSXWorkbook.WorkbookProtectHash 公開載入或產生的舊式活頁簿保護雜湊,通常是四位十六進位數字,沒有密碼雜湊時是空字串;變更保護請用活頁簿保護方法,不要指派這個唯讀值,並把活頁簿結構保護與加密檔案儲存分開看待

TXLSXWorkbook.ThemeMajorFont 與 TXLSXWorkbook.ThemeMinorFont 公開從佈景主題載入的標題與內文字型,並在產生預設 Office 佈景主題時覆寫名稱;原樣保留的佈景主題優先於這些字型名稱設定

資料表樣式與序列化器樣式池

TXLSXWorkbook.DefaultTableStyleName 與 TXLSXWorkbook.DefaultPivotStyleName 對新插入的 Excel 資料表與樞紐分析表往返讀寫樣式表中儲存的預設名稱;指派它們不會直接重新格式化所有既有物件

TXLSXWorkbook.ResolveTableStyle 依名稱回傳活頁簿持有的自訂樣式,否則解析並快取受支援的內建 TableStyleLight1 到 TableStyleLight21、TableStyleMedium1 到 TableStyleMedium28,或 TableStyleDark1 到 TableStyleDark11,未知名稱回傳 nil;不要釋放回傳的樣式

TXLSXWorkbook.FastStyleAppend 預設 False,讓大量建立跳過樣式池的去重掃描與一般複合樣式註冊,以較大的樣式表換取建立許多相異樣式時更快的插入

function TXLSXWorkbook.RegisterCompositeXf(
  AFont, AFill, ABorder, ANumFmt, AAlign, AProt: Integer): Integer; overload;
function TXLSXWorkbook.RegisterCompositeXf(
  AFont, AFill, ABorder, ANumFmt, AAlign, AProt,
  ABuiltinNumFmt: Integer): Integer; overload;
function TXLSXWorkbook.RegisterLinkedCompositeXf(
  AFont, AFill, ABorder, ANumFmt, AAlign, AProt,
  AParentXfId: Integer; ALinkedParts: TXLSXFormatParts): Integer;

TXLSXWorkbook.RegisterCompositeXf 註冊合併的字型、填滿、框線、數字格式、對齊與保護索引,回傳絕對 cellXfs 索引,不是複合池槽位;七引數多載接受內建數字格式 ID,其優先於提供的自訂格式索引,零代表不覆寫

TXLSXWorkbook.RegisterLinkedCompositeXf 額外記錄父樣式 XF ID 與連結到該父系的格式部分,不同的父系或連結組合保留各自條目;同樣回傳絕對 cellXfs 索引

TXLSXWorkbook.CompositeXfBase 回傳第一個絕對複合索引,依目前的一維樣式池計算;TXLSXWorkbook.CompositeXfCount 計數已註冊的複合條目。GetCompositeXf 使用的池槽位是絕對索引減去基底,而池成長時基底可能改變,所以這些值屬於目前的序列化狀態

TXLSXWorkbook.RegisterCondDxf 註冊借用的 TXLSDxfStyle 參照並回傳其以零為基底的差異樣式 ID,同一物件參照會重用既有 ID;序列化使用它的期間請讓物件保持存活

TXLSXWorkbook.ResetCondDxfs 清空作用中註冊表數量而不釋放借用樣式,TXLSXWorkbook.CondDxfCount 回報該數量;儲存準備會重建這個註冊表,所以不要把這些 ID 獨立於正在寫出的套件而持久化

TXLSXWorkbook.PivotCaches 是活頁簿持有的 TXLSPivotCaches 集合,由工作表樞紐分析表共用;AddPivotTable 重用相符的來源快取或建立一個,RefreshPivotCache 重新整理指定快取並保留受支援的成員識別

計算整合

TXLSXWorkbook.RecalcThreads 預設零,零或一使用序列重算,更大的值讓工作者執行緒評估獨立的公式前緣;含動態陣列的活頁簿不論此設定一律用序列輪,假設分析資料表節點維持序列,工作者使用的使用者函式處理常式必須是執行緒安全

TXLSXWorkbook.SolveCycleIteratively 是通常由 Recalculate 在啟用迭代時呼叫的進階入口,從該活頁簿目前的相依性圖形取用節點索引,並在提供的 TList 中評估循環節點;工作區圖形或其他活頁簿的索引不可互換

求解器使用 IterateCount 與 IterateDelta,即使達到迭代上限也保留最終值,並回傳 lxOk 而不為收斂背書;動態陣列循環成員回傳 lxErrorCircumRef,簽章的 CycleCount 引數不取代圖形節點上的循環分類

工作區相依性圖形建構

TXLSWorkspaceDepGraph 跨呼叫端提供的活頁簿識別與工作表識別儲存公式相依,不開啟活頁簿也不評估公式;從當前公式與已解析參照建構圖形,並在使那些參照失效的結構或公式變更後重建

function TXLSWorkspaceDepGraph.AddNode(
  const AWorkbookIdentity, ASheetName: WideString;
  ASheetIndex, ARow, ACol, AOutRow2, AOutCol2: Integer;
  AVolatile: Boolean; AReferences: TXLSWorkspaceDepReferenceList;
  ARefUnstable: Boolean = False): Integer;
procedure TXLSWorkspaceDepGraph.DirtyTopoOrder(AOrder: TList;
  out ACycleNodeCount, ABlockedNodeCount: Integer);

TXLSWorkspaceDepGraph.AddNode 附加公式節點並回傳其以零為基底的節點索引,複製提供的參照而不取得清單擁有權;工作表索引為 1 為基底,而列與欄座標,包括含端輸出矩形的右下角,都是計算器的以零為基底座標

TXLSWorkspaceDepReferenceList.Add 附加已解析的儲存格、範圍或定義名稱參照記錄,TXLSWorkspaceDepReferenceList.Items 以零為基底索引讀取那些記錄,TXLSWorkspaceDepReferenceList.Clear 重設清單供重用;這個輸入清單由呼叫端持有,可以在 AddNode 複製完條目後清空或釋放

TXLSWorkspaceDepGraph.BuildEdges 以公式輸出矩形解析已儲存的儲存格與範圍參照;標記 LookupScan 的參照會傳遞變動,但不施加評估順序,也不參與循環偵測

TXLSWorkspaceDepGraph.NodeIndexOf 把活頁簿、工作表、列與欄解析成以零為基底的節點索引,缺席時回傳 -1,有工作表名稱就用名稱,否則以宣告的工作表索引為後備

TXLSWorkspaceDepGraph.FindDependentsOfDefinedName 清空提供的非 nil TList,並填入直接參照指定活頁簿與範圍中該具名符號的節點索引,負的範圍索引符合所有範圍;條目編碼為 Pointer(NativeInt(NodeIndex)),所以 nil 清單條目可以代表節點零

工作區待重算世代與評估順序

TXLSWorkspaceDepGraph.BeginDirtyGeneration 開始新世代,重設作用中的待重算節點數與循環阻擋旗標,並使較早的待重算戳記失效;為新的一輪重算標記節點之前先呼叫它

TXLSWorkspaceDepGraph.MarkAllDirty 標記目前世代的所有節點;TXLSWorkspaceDepGraph.MarkWorkbookDirty 以屬於指定活頁簿的節點與參照它的節點為種子,再往外傳遞給相依者;TXLSWorkspaceDepGraph.MarkVolatileDirty 以揮發性節點為種子,TXLSWorkspaceDepGraph.MarkCyclesDirty 以偵測到的循環元件為種子,同樣傳遞其變動

TXLSWorkspaceDepGraph.IsNodeDirty 回報有效節點是否帶目前世代戳記,無效索引回傳 False;TXLSWorkspaceDepGraph.DirtyGeneration 公開該戳記,TXLSWorkspaceDepGraph.DirtyNodeCount 計數在作用中世代被標記的節點

TXLSWorkspaceDepGraph.DirtyTopoOrder 要求非 nil 且由呼叫端持有的 TList,清空後以相依順序填入待重算節點索引,排除待重算的循環節點與被那些循環阻擋的節點;兩個輸出數量區分循環成員與被阻擋的下游節點,清單條目使用同樣的指標編碼、以零為基底的索引慣例

TXLSWorkspaceDepGraph.HasRefUnstable 回報是否有節點以參照不穩定旗標加入,讓呼叫端在公式參照可能在評估時改變的情況下,避免依賴過時的靜態排程;圖形本身不會解析那些會變動的參照

工作區圖形檢視

TXLSWorkspaceDepGraph.NodeCount 計數公式節點,TXLSWorkspaceDepGraph.ReferenceCount 計數已複製的參照,TXLSWorkspaceDepGraph.EdgeCount 回報已建構的相依邊;消費邊統計之前先呼叫 BuildEdges

TXLSWorkspaceDepGraph.WorkbookCount 計數已駐留的活頁簿識別,包括由參照引入的識別,TXLSWorkspaceDepGraph.WorkbookIdentities 以零為基底索引列舉它們;這些識別字串是圖形鍵,不代表外部檔案真的被載入

TXLSWorkspaceDepGraph.ComponentCount 回報元件建構後的強連通元件數量,建構由 MarkCyclesDirty、DirtyTopoOrder 或元件存取觸發;每個 Components 記錄提供 NodeStart、NodeCount 與 IsCycle

TXLSWorkspaceDepGraph.ComponentNodes 公開那些元件攤平的以零為基底節點索引陣列,索引範圍從元件的 NodeStart 到 NodeStart + NodeCount - 1;數量與索引記錄描述目前的圖形,圖形重建後應重新取得

一般活頁簿進入點請繼續參閱其他 XLSX 外觀成員與XLSX 外觀總覽