HotXLS Docs
HomeContentsCalculation engine

上下文公式求值

经典 XLS 和 XLSX 工作表公开相同的只读 API，用于把公式文本当作输入到指定的从 1 开始的行和列中进行求值

一次性求值

function EvaluateFormulaAt(Row, Col: Integer;
  const Formula: WideString): TXLSFormulaEvaluationResult; overload;

function EvaluateFormulaAt(Row, Col: Integer;
  const Formula: WideString;
  ReferenceStyle: TXLSFormulaReferenceStyle;
  const Options: TXLSFormulaEvaluationOptions): TXLSFormulaEvaluationResult; overload;
工作表提供本地名称、非限定引用、表格和外部链接上下文，而不会更改活动工作表、选区、单元格模型、公式缓存、脏状态或依赖关系图
xlfrsA1 在从目标单元格解析相对引用的同时保留绝对引用和混合引用； xlfrsR1C1 直接从该目标解析相对偏移
没有显式引用的 CELL 检查提供的目标单元格；用 $A$1 可以从任意目标检查固定的第一个单元格，而 A1 在 A1 上下文契约下相对该目标解析
基于模型的 CELL 元数据和 INFO("recalc") 也可通过只读工作簿视图工作，不改变其世代或存储的公式缓存； CELL("width",reference) 保留其单行两列数组，无法归类的自定义格式返回 xlfeUnsupportedFunction 而不是凭空编造的格式代码；完整的无头与区域设置边界参见 CELL 与 INFO 元数据

类型化结果

FORMULATEXT 通过两个工作表引擎和只读视图检查存储的公式元数据，而不计算被检查的目标； GETPIVOTDATA 对本地数据透视表既有缓存的分离快照求值，并遵守求值预算和取消；缺失的可见聚合仍是类型化的 #REF! 值，不完整或不受支持的数据透视表模型返回 xlfeUnsupportedFunction；存储、数组和缓存边界参见 公式文本检查和 可见的数据透视表数据
TXLSFormulaEvaluationResult 返回 Status、原始的类型化 Value、 IsVolatile，以及一个包含状态、本机代码和消息的稳定 Issue 记录 
TXLSFormulaEvaluationStatus = (xlfeOk, xlfeInvalidArgument,
  xlfeWorksheetUnavailable, xlfeParseError, xlfeUnsupportedFunction,
  xlfeCircularReference, xlfeExternalReferenceDenied, xlfeCancelled,
  xlfeResourceLimit, xlfeFailed, xlfeUnsafeFunctionDenied);

TXLSFormulaEvaluationIssue = record
  Status: TXLSFormulaEvaluationStatus;
  NativeCode: Integer;
  Message: WideString;
end;
Formula values such as #DIV/0!、 #REF!之类的公式值、空字符串、数组、布尔值和日期仍然是可区分的值；解析失败、不受支持的函数、循环引用、被拒绝的外部引用、被拒绝的不安全回调、取消、无效参数、不可用的工作表以及资源耗尽都使用显式的 API 状态 Issue.NativeCode 携带底层引擎错误码，而 Issue.Message the human-readable description when Status is not xlfeOk

可重用的不可变模板

function CreateFormulaEvaluationTemplate(Row, Col: Integer;
  const Formula: WideString;
  ReferenceStyle: TXLSFormulaReferenceStyle): IXLSFormulaEvaluationTemplate;
模板在其锚点处对公式编译一次，并公开 EvaluateAt 和 EvaluateAtWithOptions ，以便在不同的目标单元格处重复求值
普通的 A1 和 R1C1 公式直接重用已编译的树；其含义取决于目标表格行的 A1 结构化引用则会针对该目标上下文进行解析和编译
模板不保留任何可写的工作表状态，在工作簿销毁之后会安全地报告 xlfeWorksheetUnavailable ，并在工作簿的更改使原始编译上下文过时的时候回退到可感知上下文的重新编译

资源、外部引用与回调选项

AllowExternalReferences默认为 true，但只允许显式注册的工作区目标或文件本地缓存，绝不执行隐式的文件或网络访问
AllowUnsafeFormulaCallbacks默认为 false，在求值任何参数之前阻止危险的函数名进入用户函数注册表或回调；被拒绝时返回 xlfeUnsafeFunctionDenied
CancelFlag可选的布尔指针，在求值之前和之后检查
MaxFormulaLength默认为 8192 个 UTF-16 代码单元
MaxEvaluationSteps默认为 1,000,000 次语法项求值
MaxRecursionDepth默认为 256 层嵌套公式求值
MaxArrayBytes生成的数组负载默认为 64 MiB
为零或负数的最大值会禁用相应的单次调用限制；工作簿级别的数组内存策略仍然适用，达到已启用的限制会在释放临时求值状态之后返回 xlfeResourceLimit （随后释放临时求值状态）
接受显式选项的重载把 AllowUnsafeFormulaCallbacks 视为该次调用的权威设置；默认的一次性求值和模板求值则继承工作簿的同名属性

Delphi 示例

Template := Sheet.CreateFormulaEvaluationTemplate(2, 2,
  '=R[-1]C[-1]+1', xlfrsR1C1);

Result := Template.EvaluateAt(2, 2);
if Result.Status = xlfeOk then
  UseValue(Result.Value);

Options := XLSDefaultFormulaEvaluationOptions;
Options.MaxEvaluationSteps := 10000;
Result := Template.EvaluateAtWithOptions(20, 4, Options);

C++Builder 示例

Lxcalc::_di_IXLSFormulaEvaluationTemplate evalTemplate =
  sheet->CreateFormulaEvaluationTemplate(1, 1,
    WideString(L"=ROW()+COLUMN()"), Lxcalc::xlfrsA1);

Lxcalc::TXLSFormulaEvaluationResult result =
  evalTemplate->EvaluateAt(7, 8);

直接的 正则表达式后端 API 记录了逐实例匹配、替换、状态值和调用方预算

REGEX 公式共享当前求值上下文的工作量、内存和取消控制，包括 PCRE2 工作区和输出分配；取消或资源限制产生显式状态，不会给出部分提取或替换结果

GROUPBY 与 PIVOTBY 在当前上下文中汇总分离的数组或工作表区域快照，包括捕获的 Lambda 环境、分组索引、回调向量和输出存储；资源限制和取消返回显式状态，不改变工作表数据、缓存或布局

另请参阅

TXLSWorksheet.Calculate 方法
IXLSWorkbook.Calculate 方法
Excel 计算引擎