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 这类受跟踪属性设置器会设置它,直接赋值的扩展元数据不会自动设置

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 默认为零,零或一时串行重算,更大的值启用工作线程对独立公式前沿求值;含动态数组的工作簿无论该设置如何都用串行遍历,What-If 数据表节点保持串行,工作线程使用的用户函数处理器必须线程安全

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 门面概览