HotXLS 文档

事务性数据透视表缓存刷新

版本 2.384.92 刷新本地矩形、定义名称与表格类数据透视表源，不改变既有的字段对象、共享项对象或逻辑成员索引；共享同一缓存的所有数据透视表视图继续引用相同的成员

工作簿刷新

Workbook.Recalculate;
if Workbook.RefreshPivotCache(Pivot.CacheId) <> 1 then
  raise Exception.Create('Pivot cache refresh failed');

TXLSXWorkbook.RefreshPivotCache 在刷新成功后返回 1，缓存、源、模式或源值无法刷新时返回 -1；它读取当前单元格值，所以源公式需要求值时应先重算工作簿

矩形源使用既有的本地工作表和一个表头行；SourceFirstRow、SourceFirstCol、SourceLastRow、SourceLastCol 使用含端点的 1 基坐标，第一行提供字段名

定义名称与表格源

SourceIsNamedRange=True 时，SourceName 标识一个定义名称或唯一的表名/显示名；刷新与物化在每次调用时解析其当前几何，同时保留缓存中存储的源身份

SourceRangeSheet 为本地定义名称提供工作表上下文；该作用域优先于同拼写的工作簿名称，其他情况下按工作簿作用域解析，不会误选无关的本地名称

定义名称必须包含一个显式带工作表限定的绝对矩形；支持带引号和 Unicode 的工作表名称，而相对引用、并集、别名、公式、外部引用以及含糊的名称/表冲突会在变更前被拒绝

表格必须保留表头行；记录跟随其当前范围并排除真实的总计行，而冲突检查保护包括总计在内的整个表格；只有表头的表格提供零条记录

物理总计成员关系跟随存储的 totalsRowCount，缺省即零；仅有总计 UI 提示不会移除数据行，保存时会显式写出真实成员关系

对编写出的总计行，请通过 ColumnTotalsRowLabels、ColumnTotalsRowFunctions 与 ColumnTotalsRowFormulas 提供有效的列总计元数据和工作表内容；设置 TotalsRowShown=True 不会创建总计公式，也不会强制转换单元格值

工作表移动保留本地名称作用域，工作表重命名会更新受支持的本地引用与数据透视表源上下文，同时保留无关的外部引用和不透明的导入缓存 XML；定义名称保存会移除可选的前导公式等号，而不改动内存中的公式

表头按名称与既有数据库字段匹配，不区分大小写；源列重排保留逻辑字段索引，而重复、重命名、缺失或多余的源字段会被拒绝；空表头沿用既有的 FieldN 回退

空源单元格保持为空，不会被加入工作表单元格集合；只有表头的源产生零条记录，同时保留历史成员

稳定成员与共享视图

既有共享项保留其索引与对象身份，新的类型化值追加到域中；重排、移除以及稍后重新引入源成员时，已指向这些成员的隐藏项、页选择、基础项引用与显式分组映射都保持不变

共享同一缓存的所有视图都能看到刷新后的记录；缺失的历史成员仍留在缓存域中，但不会凭自己生成聚合行，因为 TXLSPivotTable.Make 是基于当前记录构建结果的

无论 MissingItemsLimit 如何，历史成员都会保留；这条刷新路径不清除缺失成员、不执行保留成员上限，也不重排选择索引

数字、日期、布尔、文本、空白和可表示的错误值在刷新与 XLSX 保存过程中保持类型；共享项内容标志与可表示边界会基于保留的和新追加的域重新计算

保存会先补全已刷新视图的成员列表，再处理尾部分类汇总项，同时保持既有顺序、隐藏标志和导入的布局扩展；页选择在逻辑缓存成员与每个视图存储的位置之间映射，因此重排后的成员列表在重新打开后仍选中同一成员

计算字段与分组字段

计算字段不消耗源列；其名称、公式和共享项域保持可用，而每条刷新后的记录都为这些字段准备空占位；Make 基于当前源值求值受支持的计算公式

XLSX 缓存记录只存数据库字段；即使计算字段位于数据库字段之间，保存与重新打开也保持源列对齐

对源字段的数字与日期分组可以接受新成员；显式离散分组接受重排后的既有成员，但拒绝没有显式映射的新成员，并完整保留上一个缓存

版本 2.384.94 从经过校验的基础/父级链接重建受支持的固定派生分组字段；自动域扩张、未映射的离散成员和成员属性字段以事务方式拒绝，外部与 OLAP 源仍不在本地源契约之内；分组缓存边界参见 分组缓存边界

原子更新与回调刷新

源校验、读取、类型转换、记录分配和成员查找都在分离的暂存数据中完成；失败时活动的字段与项句柄、记录、元数据、原始重放状态以及所有共享视图都完好无损

成功会替换记录与查找缓冲、禁用原始缓存重放、更新 RefreshedDate 并设置 RefreshOnLoad=False；保存使用刷新后的类型化缓存，而不是重放其先前的原始表示

独立或 Classic 支撑的代码可以通过 TXLSPivotCache.RefreshFromSource 使用同一套暂存实现；其读取器收到 1 基源坐标并返回 Variant，校验或读取器失败会抛出异常

TlxPivotSourceCellValue = function(ARow, ACol: Integer): Variant of object;
procedure TXLSPivotCache.RefreshFromSource(AValueReader: TlxPivotSourceCellValue);
procedure TXLSPivotCache.RefreshFromSource(AValueReader: TlxPivotSourceCellValue;
  AFirstRow, AFirstCol, ALastRow, ALastCol: Integer);

单参数重载要求缓存中已有明确的本地矩形；显式边界重载读取调用方解析的本地矩形，不改变缓存的命名或表格源身份，正确解析该身份仍是调用方的责任

缓存刷新只更新缓存数据；应用可以带着自己的结果写入器调用 Make，或调用 MaterializePivotTable 获得受保护的工作表输出；受支持导入绑定可使用类型化非 OLAP 数据透视表 Slicer 选择，完整的原生布局仍是独立工作