附加的经典 XLS API 成员 - HotXLS 开发者参考

本页介绍属于 lxHandle、lxDataToXLS 和 lxGridToXLS 的公共经典 XLS API 成员

IXLSWorkbook 计算属性

property CalculationMode: LongWord;
property FormulaArrayMemoryLimit: Int64;
property EnableIteration: Boolean;
property MaxIterations: LongWord;
property MaxIterationChange: Double;
property RecalcOnSave: Boolean;
property UseFullPrecision: Boolean;

CalculationMode	控制随文件一起保存的工作簿计算模式
FormulaArrayMemoryLimit	限制 `MUNIT` 等生成的公式数组所分配的载荷大小，默认 64 MiB，并把低于一个 `Double` 元素的值钳制到下限
EnableIteration	为循环引用公式启用迭代计算
MaxIterations	每个循环引用强连通分量的最大 Gauss-Seidel 迭代轮数
MaxIterationChange	循环引用分量停止迭代前可接受的最大数值变化量
RecalcOnSave	请求 Excel 保存文件时重新计算工作簿
UseFullPrecision	保持公式的完整精度；禁用时，公式和 What-If 数据表缓存会先按其有效显示数值精度舍入，再供依赖方读取

公式输入验证

property IXLSWorkbook.FormulaEntryPolicy: TXLSFormulaEntryPolicy;
function TXLSWorksheet.ValidateFormulaEntry(Row, Col: Integer;
  const Formula: WideString): TXLSFormulaEntryValidationResult;

共享的验证契约对空输入、未知函数、未知名称、语法错误、无效坐标以及无法用 Classic XLS 目标表示的公式进行分类，且不改变工作表状态；参见公式输入验证策略

IXLSWorkbook 渲染校准

property RenderCalibration: TXLSRenderCalibration;
function CaptureRenderCalibration: TXLSRenderCalibration;
procedure ResetRenderCalibration;
function CreateRenderGeometry(ABackend: TXLSRenderGeometryBackend;
  ACacheCapacity: Integer = 4096): IXLSRenderGeometry;

整记录赋值会在修改工作簿之前校验全部六个字段，CaptureRenderCalibration 为单次测量或导出操作返回一个独立的值快照，ResetRenderCalibration 则恢复标准的 1/1/1/1/100/96 值

这份仅运行时的配置不会序列化进 XLS 文件，也不会修改工作表的行高或列宽

CreateRenderGeometry 把当前校准复制到一个由操作持有的服务中，并将其缓存标识绑定到当前工作簿世代和所选后端；之后工作簿校准的变化无法改动已存在的服务

区域 AutoFit 和每次 TXLSPaginationModel.Build 调用各捕获一次工作簿校准；AutoFit 是唯一会有意写入自适应尺寸的消费者，分页则保留所有已存储的行高和列宽

IXLSWorkbook 文档属性

property Title: WideString;
property Subject: WideString;
property Author: WideString;
property Keywords: WideString;
property Comments: WideString;
property Company: WideString;
property Manager: WideString;

这些属性读写随经典 XLS 文件一起保存的工作簿摘要信息字段

IXLSWorkbook Close 方法

function Close: Integer;

关闭工作簿对象，并释放由经典 XLS 对象模型持有的工作簿所拥有的内容

IXLSWorkbook 仅元数据加载属性

property MetadataOnly: Boolean;
property SelectedSheets: TStringList;
property IncompleteLoad: Boolean;

MetadataOnly	在 `Open` 之前设置时，只读取工作簿元数据和工作表描述符，跳过单元格数据
SelectedSheets	打开工作簿时要加载的工作表名称列表；空列表加载全部工作表
IncompleteLoad	当因使用 `MetadataOnly` 或 `SelectedSheets` 而跳过单元格数据时，`Open` 之后为 True

以 MetadataOnly 或非空 SelectedSheets 打开的工作簿无法保存；在未带这些选项重新打开工作簿之前，Save 会抛出错误

TXLSColumnInfo 折叠状态

property TXLSWorksheet._ColumnInfo: TXLSColumnInfoList;
property TXLSColumnInfo.Collapsed: Boolean;
property TXLSRowInfo.Collapsed: Boolean;
property TXLSColumnInfoList.Collapsed[Index: Integer]: Boolean;

Collapsed 独立于 Hidden 和 OutlineLevel 公开 BIFF 列分级显示标记。列表索引是从 0 开始的经典 XLS 列索引。缺失的列读取为 False，对缺失的列赋值 False 不会分配元数据。列格式复制、工作表复制以及保存后重新打开都会保留该标记

底层存储访问器是公开的，便于对工作簿做底层检查。TXLSRowInfo 报告 MinCol 和 MaxCol（覆盖的从 1 开始的列区段）、CustomHeight 和 CustomFormat（是否存储了显式高度或 XF 索引）以及 XFIndexSet；TXLSColumnInfo.isEqual 逐字段比较两个列元数据条目

TXLSColumnInfoList 公开 ColCount、MinCol、MaxCol、StdWidth 和 MaxOutlineLevel 用于边界与默认列宽诊断；CalcMaxOutLineLevel 在直接编辑元数据后重新计算缓存的最大分级显示级别；CopyColFormat 把一个列条目克隆到另一个索引上；DeleteCol 删除一个条目；FindNextColToStore 为 BIFF COLINFO 记录写入器遍历已存储的条目，并通过 MinCol / MaxCol 出参报告下一个区段

TXLSWorksheet 分级显示节点方法

function TryGetOutlineNode(AAxis: TXLSOutlineAxis; ANodeIndex: Integer; out ANode: TXLSOutlineNode): Boolean;
function SetOutlineNodeCollapsed(AAxis: TXLSOutlineAxis; ANodeIndex: Integer; ACollapsed: Boolean; AChildMode: TXLSOutlineChildMode = xocPreserve): Boolean;
procedure SetOutlineDisplayLevel(AAxis: TXLSOutlineAxis; ADisplayLevel: Integer; AChildMode: TXLSOutlineChildMode = xocPreserve);

这些方法把经典的行和列元数据适配到共享的稀疏分级显示模型上，从分级显示方向推导所请求的汇总节点，并以压缩的方式应用隐藏和折叠变更，而无需探测未使用的工作表坐标

ANodeIndex 是从 1 开始的物理汇总行或列，ADisplayLevel 遵循从 1 开始的分级显示按钮约定，xocPreserve 默认让嵌套子级的折叠标记保持独立

节点字段、子级模式、示例和复杂度保证参见稀疏分级显示几何

TXLSWorksheet 窗格与打印标题方法

function ThawPanes(Y, X: Single; RowTop, ColLeft: Word): Integer;
function SplitPanes(Width, Height: Single): Integer;
function UnsplitPanes: Integer;
function GetSelectedAreas(APane: TXLSPanePosition; out ActiveAreaIndex: Integer): TXLSSelectedAreas;
function SelectAreas(APane: TXLSPanePosition; const Areas: array of WideString; ActiveAreaIndex: Integer = 0): Boolean;
function TryGetWindowScroll(APane: TXLSPanePosition; out ARow, ACol: Integer): Boolean;
function ScrollWindow(APane: TXLSPanePosition; ARow, ACol: Integer): Boolean;
function RepeatRows(FirstRow, LastRow: Word): Integer;
function RepeatColumns(FirstCol, LastCol: Word): Integer;

ThawPanes、SplitPanes 和 UnsplitPanes 控制拆分窗格状态，而 RepeatRows 和 RepeatColumns 用于设置工作表的打印标题行或列

GetSelectedAreas 和以窗格为先的 SelectAreas 重载提供共享的逻辑窗格选择契约，描述见工作表窗格选择

同一窗格的连续 BIFF 选择记录构成单个逻辑组，编辑过的组按最多 1369 个区域分块写出，工作表复制会保留每个窗格组

整行和整列的结构性编辑会重映射每个有效的窗格组，同时按顺序保留幸存区域和活动区域标识，并对后继、前驱和边界单元格采用确定性的回退

格式错误或自相矛盾的选择记录保持不透明，保存时按字节原样重放，并报告 xlsDiagnosticSelectionRecordInvalid 诊断，而不是暴露部分可信的类型化状态

TryGetWindowScroll 和 ScrollWindow 公开共享的从 1 开始的四窗格滚动契约，把上方和左侧轴映射到 Window2，把下方和右侧轴映射到 Pane

TXLSWorksheet 类型化数据验证方法

function AddWholeNumberValidation(ARange: WideString; AOp: TXLSDvOperator; const AFormula1: WideString; const AFormula2: WideString = ''): TDataValidation;
function AddDecimalValidation(ARange: WideString; AOp: TXLSDvOperator; const AFormula1: WideString; const AFormula2: WideString = ''): TDataValidation;
function AddDateValidation(ARange: WideString; AOp: TXLSDvOperator; const AFormula1: WideString; const AFormula2: WideString = ''): TDataValidation;
function AddTimeValidation(ARange: WideString; AOp: TXLSDvOperator; const AFormula1: WideString; const AFormula2: WideString = ''): TDataValidation;
function AddTextLengthValidation(ARange: WideString; AOp: TXLSDvOperator; const AFormula1: WideString; const AFormula2: WideString = ''): TDataValidation;
function AddCustomValidation(ARange: WideString; const AFormula: WideString): TDataValidation;

每个辅助方法为 ARange 创建一条类型化数据验证规则，并返回所创建的 TDataValidation 实例，以便调整提示、错误和空白处理选项

TXLSWorksheet 数据透视表成员

property PivotTables: TXLSPivotTables;
function AddPivotTable(const SourceRangeA1: WideString; DestRow, DestCol: Integer; const Name: WideString): TXLSPivotTable;
function PivotSetDataFieldFormat(DataField: TXLSPivotDataField; const FormatStr: WideString): Word;

使用 AddPivotTable 从来源范围创建类型化数据透视表，然后使用 PivotTables 和 PivotSetDataFieldFormat 检查或格式化所生成的模型。参见经典 XLS 数据透视表 API

IXLSRange 数组公式与边界成员

function SetArrayFormula(const Formula: WideString): Integer;
function XFIndex: Integer;
property FirstRow: Word;
property LastRow: Word;
property FirstCol: Byte;
property LastCol: Byte;

SetArrayFormula 将数组公式分配给范围。FirstRow、LastRow、FirstCol 和 LastCol 公开存储的从 1 开始的范围边界，而 XFIndex 返回该范围的有效经典 XLS 格式索引

IXLSRange 传输辅助方法

procedure PasteFrom(SrcRange: TXLSRange; PasteMode: LongWord; CopyMode: Boolean);
procedure ShiftTo(Row: Word; Col: Byte);
procedure ExtendRange;
procedure ContractRange;

PasteFrom 使用所选粘贴模式，从另一个经典 XLS 范围应用单元格内容。ShiftTo 重新定位范围对象，而 ExtendRange 和 ContractRange 在需要扩展或规范化边界的范围操作之前调整所存储的矩形

IXLS 行与列范围接口

interface IXLSRowsRange = interface(IXLSRange)
  property Item[Row: Integer]: IXLSRowRange;
  property Hidden: OleVariant;
  property Count: LongWord;
  procedure AutoFit(Columns: Boolean = False);

interface IXLSRowRange = interface(IXLSRange)
  property Item[Col: Integer]: IXLSColRange;
  property Hidden: OleVariant;
  property Count: LongWord;
  procedure AutoFit(Columns: Boolean = False);

interface IXLSColsRange = interface(IXLSRange)
  property Item[Col: Integer]: IXLSColRange;
  property Hidden: OleVariant;
  property Count: LongWord;
  procedure AutoFit(Columns: Boolean = True);
  procedure Group(Rows: Boolean = False);
  procedure UnGroup(Rows: Boolean = False);
  property OutlineLevel: Integer;

interface IXLSColRange = interface(IXLSRange)
  property Item[Row: Integer]: IXLSRowRange;
  property Hidden: OleVariant;
  property Count: LongWord;
  procedure AutoFit(Columns: Boolean = True);
  procedure Group(Rows: Boolean = False);
  procedure UnGroup(Rows: Boolean = False);
  property OutlineLevel: Integer;

IXLSRowsRange、IXLSRowRange、IXLSColsRange 和 IXLSColRange 由 IXLSRange.Rows、IXLSRange.Columns、IXLSRange.EntireRow 和 IXLSRange.EntireColumn 返回。它们保留常规的 IXLSRange 编辑能力，并在范围方向支持的情况下增加了索引化的行或列访问、隐藏状态控制、计数、自动调整以及大纲分组

IXLSHyperLink DisplayText 属性

property DisplayText: WideString;

DisplayText 读取或更改 Excel 为经典 XLS 超链接显示的可见文本，与目标地址和屏幕提示分离

TXLSWorksheets ID 映射属性

property IndexByID[SheetID: Integer]: Integer;
property IDByName[SheetName: WideString]: Integer;
property NameByID[SheetID: Integer]: WideString;

这些只读查找属性用于在内部工作表 ID、当前工作表索引与可见工作表名称之间进行映射。当需要保留按存储标识符（而非当前标签顺序）引用工作表的公式、定义名或记录时，这些属性非常有用

TXLSWorksheet SheetTypeRaw 属性

property SheetTypeRaw: Byte;

SheetTypeRaw 在加载和保存工作簿时保留原始的经典 XLS BoundSheet8.dt 值，使宏、VBA、工作表、对话框及其他工作表类型记录能够完整往返，而不会被扁平化为标准工作表标签

IXLSPageSetup 高级打印属性

property PrintNotesAtEnd: Boolean;
property UseFirstPageNumber: Boolean;
property FirstPageNumber: Integer;
property PrintCellErrors: LongWord;
property PrintResolution: LongWord;
property PrintVResolution: LongWord;
property Copies: LongWord;
property HasSetupRecord: Boolean; read only
property PrinterSettingsInitialized: Boolean; read only
property PrinterDriverData: TBytes;
property HasPrinterDriverData: Boolean; read only
procedure ClearPrinterDriverData;

这些属性保留高级页面设置选项，例如在末尾打印批注、自定义起始页码、打印的单元格错误渲染、打印机分辨率以及打印份数

HasSetupRecord 报告已加载的经典 XLS 工作表是否包含 BIFF Setup 记录，而 PrinterSettingsInitialized 报告其纸张大小、缩放、方向、分辨率和打印份数是否由该记录定义

保存未经改动的工作表时，缺失的 Setup 记录保持缺失，已有记录按字节原样保留；修改页面设置字段会在需要时创建该记录，修改依赖打印机的字段则会初始化打印机设置

PrinterDriverData 读取或替换不透明的 BIFF PLS 打印机驱动载荷，HasPrinterDriverData 用于区分载荷是否存在，ClearPrinterDriverData 移除载荷且不改动类型化的页面设置字段

getter 和 setter 都会复制字节数组，调用方和工作表副本各自持有独立的数组；Classic 载荷必须包含必需的两字节保留前缀，且不能超过 1 MiB

SaveXLSWorkbookAsXLSX 会把类型化的页面设置值和不透明的打印机驱动载荷相互独立地带入 XLSX 模型；当私有驱动字节里含有重复的打印机默认值时，仍以类型化标准字段为准

IXLSFont 字符集属性

property CharSet: Byte;
property Family: Byte;

CharSet 和 Family 公开经典 XLS 字体的字符集与字体族字节，供需要保留区域设置相关字体元数据的调用方使用

TDataToXLS 与 TGridToXLS Abort 方法

procedure TDataToXLS.Abort;
procedure TGridToXLS.Abort;

当正在运行的数据集或网格导出必须在完成之前停止时，可从导出事件处理程序中调用 Abort

经典 XLS 引用辅助函数

function GetCellRef(Cell: String; var Row, Col: Word): Integer;
function GetCellRange(CellRange: String; var StartRow, StartCol, EndRow, EndCol: Word): Integer;
function EncodeCellRef(Row, Col: Word): String;
function EncodeCellRange(StartRow, StartCol, EndRow, EndCol: Word): String;
function Width2Excel(Value: Single): Word;
function Excel2Width(Value: Word): Single;
function Height2Excel(Value: Single): Word;
function Excel2Height(Value: Word): Single;
function ColIndexToColName(Index: Integer): String;
function ColNameToColIndex(Name: String): Integer;

这些辅助函数转换经典 XLS 对象模型使用的 A1 引用、范围、列标签、行或列尺寸以及 Excel 存储单位