HotXLS 文档

原生数据透视表计算字段与缓存持有的项

基于上下文求和计算

对本地计算缓存字段，原生预览会先在请求的叶节点、分类汇总或总计上下文中对每个被引用的数据库字段求和，然后再求值公式；依赖项可以不出现在显示的数据字段中

例如，Amount/Units 值为 10/1 和 30/9 的两条记录产生原生计算字段结果 40/10 = 4，而总计会对自己的依赖项求和，不是把显示的比值相加

计算项在每个完整的叶节点上下文中求值成员引用，包括其他行轴与列轴；分类汇总与总计包含由此产生的成员贡献，因此一个比值项可以贡献其叶节点比值的和

手动隐藏的成员在另一个计算项引用它时仍然可用，但其自身贡献不会进入显示的总计；设 A=40、B=60，隐藏 A 后 Combined=A+B 的值仍为 100，且 Combined 计入可见的总计

计算字段与计算项共存时，项的贡献先更新其引用的数据库字段和，然后计算字段再对这些更新后的上下文和求值

计算项可以属于多个未分组字段；保留的缓存定义顺序决定哪个字段公式最后写入某个交叉点，因此移动定义可能同时改变该交叉点和显示的总计

未解析的计算成员依赖在被引用时求值，包括定义在该顺序靠后位置的依赖；在更早步骤已经算出的成员，被另一个公式引用时保留其当前交叉点值

原生字段求和忽略布尔与文本源值，保留数字与日期值，并传播类型化的源错误；惰性的 IF 与 IFERROR 可以在不求值未用分支的情况下处理错误

缓存所有权与绑定

公开声明契约
TXLSPivotCacheCalculatedItem缓存持有的原生计算成员定义；经由所属缓存获取，使用该借用对象期间保持缓存存活
TXLSPivotCacheCalculatedItem.FieldIndex: Integer只读的从零开始缓存字段身份
TXLSPivotCacheCalculatedItem.ItemIndex: Integer只读的 FieldIndex 内从零开始共享成员身份
TXLSPivotCacheCalculatedItem.Formula: WideString可读写的原生成员公式；赋值即改变模型，而预览或显式绑定会在计算前校验语法与依赖环
TXLSPivotCacheCalculatedItem.Supported: Boolean只读，表示解析后的区域身份是否可用，并不保证每个公式或视图组合都能求值
TXLSPivotCacheCalculatedItem.RawXml: WideString只读，不受支持的计算项定义所保留的 XML；已知类型化定义为空字符串
TXLSPivotCache.AddCalculatedItem(AFieldIndex, AItemIndex: Integer; const AFormula: WideString): TXLSPivotCacheCalculatedItem为既有成员创建受支持的类型化定义，拒绝无效身份、空公式或重复的目标身份；返回对象归缓存所有
TXLSPivotCache.FindCalculatedItem(AFieldIndex, AItemIndex: Integer): TXLSPivotCacheCalculatedItem返回借用的匹配定义或 nil
TXLSPivotCache.CalculatedItemCount: Integer只读，保留中的受支持与不受支持定义数量
TXLSPivotCache.CalculatedItems[Index: Integer]: TXLSPivotCacheCalculatedItem只读，从零开始借用访问定义列表
TXLSPivotCache.ClearCalculatedItems释放持有的定义并使借用句柄失效；不移除共享成员，也不建立缓存查询完整性
TXLSPivotCache.MoveCalculatedItem(AIndex, ANewIndex: Integer)在原生求解顺序的从零开始位置之间移动既有定义，保留其借用对象身份；无效位置抛出 EArgumentOutOfRangeException 且不移动定义
TXLSPivotCache._AddUnsupportedCalculatedItem(const ARawXml: WideString)面向解析器的保留钩子，保留未知 XML 并把缓存查询模型标记为不完整
TXLSPivotCache.Assign(Source: TXLSPivotCache)深拷贝定义、字段、共享成员、记录索引与日期系统上下文；源句柄保持独立，把同一缓存赋给自身是安全的
TXLSPivotTable.BindCalculatedItemsToCache校验并绑定视图编写的计算项到分离的缓存，然后把新的共享成员与定义追加到活动缓存；失败时成员身份与定义保持不变，既有字段与成员句柄仍然有效

经 TXLSPivotField.AddCalculatedItem 创建的视图编写项，在原生物化或类型化原生重建之前需要显式 BindCalculatedItemsToCache；导入受支持的原生缓存定义时已经带有该所有权

缓存绑定影响共享该缓存的每个视图，所以请把它当作编写期操作，并只在对应列表被清理、赋值或销毁之前保留借用句柄

成员筛选与显示变换

对计算项字段做标题与值比较，是在成员公式运行之后选择显示成员；被筛选的源成员仍可被引用的公式使用，可见的分类汇总与总计排除这些成员的直接贡献

值比较可以选中一个计算度量；每个候选成员从其上下文依赖和中对该度量求值，而不是累加源记录比值，也不是把公式当作缓存记录列

计算项结果同样支持建模的 ShowDataAs 变换，包括百分比、指数、差异、累计、累计百分比与排名；隐藏成员留在可见累计与排名序列之外，而公式引用保留其原始值

公开声明契约
TXLSPivotFilter.DataFieldIsMeasureIndex: Boolean选择 DataField 的身份域；False 保持既有的从零开始缓存字段身份，True 表示从零开始的显示数据度量位置，导入原生 iMeasureFld 时会设置它
TXLSPivotFilter.SourceOrder: Integer可读写，保留自原生 filters 元素的从零开始全局顺序，缺省 -1；本地计算与类型化写入先使用非负的 EvalOrder，再是 SourceOrder，最后是稳定的字段/列表顺序

类型化原生写入会把缓存字段身份转换为显示度量位置；被多个数据度量使用的缓存字段需要显式的度量位置，否则其聚合与显示身份会有歧义

Excel 可以在 evalOrder=-1 的情况下保存活动筛选，同时经 filters 元素序列保留其求值顺序；导入、克隆与类型化重建会保留该序列，而不会把这些筛选当作不活动

修改导入的保留原生视图上的筛选定义或其保留的源位置需要类型化重建；普通的原生采纳会校验保留的筛选身份并在写入报表单元格前拒绝不受支持的编辑

预览、查询与日期系统

function TXLSPivotTable.MakePreview(AWriter: TlxPivotResultWriter;
  ALayoutWriter: TlxPivotLayoutWriter;
  AUseNativeGrandTotals: Boolean = False;
  ABudget: TlxPivotQueryBudget = nil;
  ADateSystem: TXLSPivotDateSystem = xlpdsCache): Integer;

function TXLSPivotTable.GetDataValue(const ADataField: WideString;
  const AConstraints: TXLSPivotDataConstraints;
  ABudget: TlxPivotQueryBudget; out AValue: Variant;
  ADateSystem: TXLSPivotDateSystem = xlpdsCache): Boolean;

AUseNativeGrandTotals=True 的 MakePreview 使用分离的表和缓存，包括精确的原生求和与计算项身份；普通 Make 与默认 MakePreview 保持既有的基于记录的计算行为

缓存含计算字段或计算项时，GetDataValue 使用原生上下文求和，GETPIVOTDATA 共享该查询路径；两个操作都不刷新源数据、不重算被检查的工作表公式，也不写报表单元格

公开声明契约
TXLSPivotCache.Date1904: Boolean可读写，独立原生计算所用的源日期系统上下文；默认 False，在 Classic 与 XLSX 导入、工作表缓存创建以及 XLSX 缓存复制时绑定
TXLSPivotDateSystem分离式原生预览与查询的类型化日期系统选择
xlpdsCache使用缓存保留的 Date1904 上下文而不改变它
xlpds1900把 1900 日期系统投影进分离计算
xlpds1904把 1904 日期系统投影进分离计算
TryXLSXMakeNativePivotLayout(...; ADateSystem: TXLSPivotDateSystem = xlpdsCache): Boolean更低层的原生布局帮助器在其 ResultXml 与 Reason 输出参数之后接受同样的分离日期系统选择
TXLSGetDate1904 = function: Boolean of object计算器元数据回调，读取当前所属工作簿的日期系统
TXLSCalculator.OnGetDate1904: TXLSGetDate1904GETPIVOTDATA 使用的可选借用回调；nil 时使用缓存上下文，工作簿求值器及其只读视图会提供当前工作簿设置

独立调用方必须提供正确的缓存 Date1904 上下文或显式日期系统选择；工作簿持有的原生物化与公式查询会投影当前工作簿设置，而不修改活动缓存

日期源值在缓存中保持绝对的 TDateTime 值，而原生数值公式使用 Excel 日期序列号；1904 系统对每个日期值减去 1462 天，1900 转换会处理 1900 年 3 月之前可表示的日期

保存的原生输出所有权会记录其日期系统上下文，并把带样式的日期值与其序列化的数值负载比对；保存、重新打开或修改工作簿日期基准都保留合法所有权，而日期、布尔、错误与文本负载变化仍会拒绝覆盖

预算与不受支持的输入

可选的 TlxPivotQueryBudget 回调接收工作量增量和当前内存估计，包括拟议的分离快照与公式存储；返回 False 以 EXLSPivotQueryBudget 中止，回调异常向外传播

记录宽度与数据库成员身份在克隆前检查；公式编译与求值计入工作量，计算保持有界的语法深度、公式文本、计算成员域与累加器存储

计算项规划在分配前限制合计的成员域、标题存储与字段计划；原生成员求值与晚期聚合筛选扫描也会在其固定限额内拒绝超出拟议工作量的请求，预算取消则保持活动的成员掩码不变

公式解析器支持数字常量、字段名、带引号名称、字段限定的成员名称、算术与比较、百分号，以及 ABS、SQRT、POWER、ROUND、MIN、MAX、SUM、IF、IFERROR、AND、OR 与 PI；未知函数、单元格引用、数组和未绑定名称会被拒绝，不会给出猜测值

原生计算字段要求 SUM 数据度量，不能作为行、列或页轴；计算项要求未分组缓存字段中保留的字符串标题、自动或 SUM 分类汇总、SUM 度量以及受支持的单成员区域身份

未知的公式函数、非零的区域 fieldPosition、未知或畸形的区域元数据、含糊的筛选度量身份，以及同时活动的基本与扩展显示变换都会被显式拒绝；这些限制不会把不受支持的定义变成普通项

计算成员的晚期聚合筛选支持建模的值比较；旧式计数、百分比与求和筛选变体以及未建模的 Top n 元数据要求受支持的原生选择模型，会被拒绝而不是退回源记录比较

导入的原始部件为普通往返保留而不受支持的未来元数据；本地计算、类型化重建与语义特性提取要求模型可用，且不通过刷新源数据来编造缺失的缓存记录

语义数据透视表缓存定义包括计算项身份与公式、日期系统上下文以及分离的有界负载；不可用的原生扩展仍是显式的语义错误