HotXLS 文档 / API 参考

复合文件存储

lxCompoundFile 通过 Pascal 流读写 Compound File Binary 容器,包括嵌套存储作用域、MiniFAT 负载和链式 DIFAT 扇区;原生 Classic BIFF8 工作簿 API 在 Linux 和 macOS 上使用的就是这个后端

表格处理请照常使用工作簿的 Open 与 SaveAs 调用;下面这些更底层的 API 适合检查嵌套流、构建容器以及保留存储元数据

读取或构建容器

TlxCompoundFile.LoadFromStream(AStream, AOwnsStream) 加载目录与分配元数据;AOwnsStream 默认为 False,提取内容期间底层流必须保持可用

CreateNew(AStream, AOwnsStream) 准备一个新容器,AddStorage 和 AddStream 把内容排入队列,Save 则写出带所需 DIFAT 扩展扇区的版本 3 容器

成员行为
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 刻度数,而不是按区域格式化的日期

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

提取出的流持有分离的字节缓冲,必须由调用方释放;损坏、不完整的链、无效的所有权以及成环的目录或分配图都会被拒绝,而不是返回被截断的数据

lxCfbCompareNames(A, B) 应用 Compound File Binary 的长度优先排序,并使用固定的简单 BMP 大写映射;重名以各自的父级为作用域,不同嵌套存储中的同名条目彼此独立

原生存储接口

在非 Windows 目标上,lxOLE 提供 Classic 工作簿加载与保存所需的存储接口实现;其 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 文本表示,让 Classic 定义名称存储能与其他工作簿引擎共享规范等价性

这种键表示用于身份识别与查找,而不是用于显示拼写;用户编写的名称保持不变,CFB 目录比较器仍遵循格式强制要求的独立排序

原生构建要求与经过验证的 BIFF8 工作簿契约参见 Free Pascal 支持,受支持的加密与明文属性流行为参见 Classic 加密