HotXLS 文件 / API 參考

複合檔案儲存

lxCompoundFile 透過 Pascal 串流讀寫複合檔案二進位(Compound File Binary)容器,包括巢狀儲存範圍、MiniFAT 承載與鏈結的 DIFAT 磁區;原生的傳統 BIFF8 活頁簿 API 在 Linux 與 macOS 上就是使用這個後端

試算表工作請使用普通的活頁簿 Open 與 SaveAs 呼叫;以下較底層的 API 適合用來檢視巢狀串流、建構容器與保留儲存中繼資料

讀取或建構容器

TlxCompoundFile.LoadFromStream(AStream, AOwnsStream) 載入目錄與配置中繼資料;AOwnsStream 預設為 False,而擷取內容期間底層串流必須持續可用

CreateNew(AStream, AOwnsStream) 準備新容器,AddStorage 與 AddStream 把內容排入佇列,Save 則寫出版本 3 的容器,並附上必要的 DIFAT 延伸磁區

成員行為
RootIndex根目錄項目的識別,作為頂層儲存與串流的父層
AddStorage(Name, ParentIndex)把巢狀儲存排入佇列,並回傳其目錄識別以便加入子項
AddStream(Name, Data)把根層級的位元組串流排入佇列
AddStream(Name, Data, ParentIndex)把位元組串流排入選定父範圍的佇列,並回傳其識別
OpenStream(Name), OpenStream(Name, ParentIndex)把根層或指定範圍的串流擷取為持有的 TlxCfbStream;串流不存在時回傳 nil
OpenEntryStream(Index)依識別擷取目錄串流;無效或非串流的項目回傳 nil
HasStream(Name), HasStream(Name, ParentIndex)測試根層或選定父範圍中串流是否存在
FindStorage(Name, ParentIndex)回傳選定父層中的儲存識別,沒有符合的儲存時回傳 -1
EntryCount, Entries(Index)檢視已載入的目錄項目;索引以零為基底且必須有效
SetEntryMetadata(Index, Entry)只把類別 ID、狀態位元與時間戳記複製進有效的佇列項目或根項目;結構識別與承載保持不變

TlxCfbEntry 記錄公開 Name、EntryType、StartSector、Size、LeftSibling、RightSibling、Child 與推導的 ParentIndex;目錄連結是索引,-1 表示不存在

其中繼資料欄位為 ClassID、StateBits、CreationTime 與 ModificationTime;時間戳記保留自 1601 UTC 紀元起的原始 FILETIME 刻度,而不是依 locale 格式化的日期

TlxCfbEntryType 包含 cfbEmpty、cfbStorage、cfbStream 與 cfbRoot;TlxCfbStream 公開 Name、Size、Data、Read、Seek 與 CopyTo

擷取出來的串流擁有分離的位元組,必須由呼叫端釋放;損毀、不完整的鏈結、無效的擁有權,以及循環的目錄或配置圖形都會被拒絕,而不是回傳被截斷的承載

lxCfbCompareNames(A, B) 套用複合檔案二進位格式「長度優先」的排序,並使用固定的簡單 BMP 大寫映射;重複名稱以各自的父層為範圍,不同巢狀儲存中的同名稱仍視為相異

原生儲存介面

在非 Windows 目標上,lxOLE 提供傳統活頁簿載入與儲存所需的儲存介面實作;其 IStorage、IStream 與 IEnumStatStg 保留明確的介面擁有權與分離的原生容器狀態

工廠或輔助函式契約
XlsOpenCompoundStorage(Source, Storage)從串流偏移零開始載入唯讀容器
XlsOpenCompoundStorage(Source, Start, Storage)從明確的非負偏移開始載入容器
XlsCreateCompoundStorage(Storage)建立可寫入的原生儲存,支援巢狀範圍與串流
XlsWriteCompoundStorage(Storage, Destination)把原生根儲存序列化到提供的串流;外部實作與非根儲存會被拒絕
XlsFreeCompoundStorageName(Name)釋放儲存統計或列舉回傳的原生名稱;接受 nil

工廠回傳 HResult;使用回傳的介面前請先測試 Succeeded(Result),用完後記得釋放介面參照

唯讀物件的修改會失敗,複製的串游標保持獨立位置,巢狀複製則保留父識別與受支援的中繼資料;直接序列化不提供較高層的活頁簿目的地交易契約

標準活頁簿識別

lxStandard 中的 XlsIdentifierKeyText(const A: WideString): WideString 回傳既有固定 Unicode 識別鍵的 UTF-16 文字表示,讓傳統定義名稱儲存能與其他活頁簿引擎共用標準相等性

這個鍵表示只用於識別與查詢,而不是顯示的拼寫;撰寫的名稱保持不變,CFB 目錄比較器也維持其獨立、由格式規定的排序

原生建置需求與已驗證的 BIFF8 活頁簿契約請見Free Pascal 支援,受支援的加密與明文屬性串流行為請見傳統加密