HotXLS 文档 / API 参考

数据透视表 Timeline 与 Slicer 数据状态

版本 2.384.98 起经由 XLSX 工作簿门面，对受支持的本地非 OLAP 数据透视表可用

创建并连接 Timeline

TimelineCache := Workbook.CreatePivotTimelineCache(Pivot, 'EventDate');
if TimelineCache = nil then
  raise Exception.Create('The Timeline cache was rejected');
TimelineView := ReportSheet.Timelines.Add(TimelineCache, 2, 7, 7, 12);
if TimelineView = nil then
  raise Exception.Create('The Timeline view was rejected');
if TimelineCache.SetDateRange(EncodeDate(2026, 1, 1),
    EncodeDate(2026, 1, 31)) < 0 then
  raise Exception.Create('The Timeline selection was rejected');

TXLSXWorkbook.CreatePivotTimelineCache(ATable: TXLSPivotTable; const AFieldName: WideString): TXLSXTimelineCache 创建或复用一个经过校验的日期字段缓存及其必需的包身份；失败会在提交暂存状态之前返回 nil

TXLSXWorkbook.TimelineCaches 暴露 TXLSXTimelineCaches，含 Count、从零开始的 Items[Index] 与不区分大小写的 FindByName；这些缓存由工作簿持有

TXLSXTimelineCache.Name 标识缓存，SourceName 标识其源字段，IsNonOlapPivot 标识经过校验的受支持绑定；导入的不受支持缓存保留其原始 XML

TXLSXTimelineCache.ConnectPivotTable(ATable: TXLSPivotTable): Integer 把同一 PivotCache 的另一个持有视图连接到兼容的日期字段；成功（包括既有连接）返回 1，被拒绝返回 -1

TXLSXTimelineCache.SetDateRange(AStartDate, AEndDate: TDateTime): Integer 使用含端点的整天边界，返回 1 或 -1；端点必须是 1900 年 1 月 1 日至 9999 年 12 月 31 日之间的整数日期且按升序给出

受支持的工作簿使用 1900 日期系统；Date1904 编写与小数选择端点会被拒绝，而源日期值可以保留一天中的时刻，选中结束日全天内的记录都符合条件

TXLSXTimelineCache.SelectionActive、StartDate 与 EndDate 暴露活动边界；ClearSelection: Integer 清除它们且不影响其他筛选，返回 1 或 -1

选择会与其他 Slicer、手动或页筛选以及调用方谓词求交集；这些操作不刷新源缓存、不重算公式，也不重写既有的工作表报表单元格

Timeline 视图与移除

TXLSXWorksheet.Timelines 暴露工作表持有的 TXLSXTimelines 集合，含 Add、FindByName、从零开始的 Items[Index]、Count、Delete(Index) 与 Clear；删除只移除 UI，保留其共享缓存与选择

TXLSXTimelines.Add(ACache: TXLSXTimelineCache; ARow1, ACol1, ARow2, ACol2: Integer): TXLSXTimeline 接受持有的受支持缓存和一个有序的 1 基工作表矩形，返回持有的视图或 nil

TXLSXTimeline.Name 为只读，Cache 标识其共享缓存，Caption 修改显示标签；Level 接受 0 表示年、1 表示季、2 表示月或 3 表示日

TXLSXTimeline.SetBounds 修改由 FromRow、FromCol、ToRow 与 ToCol 暴露的 1 基矩形；无效几何、不受支持的绑定或分组绘图几何会在变更前抛出异常

TXLSXDrawingObject.Timeline 对绘图类别 xlsxDrawingTimeline 返回关联视图；直接的不受支持绘图变换仍受保护

Status := Workbook.RemoveTimelineCache(TimelineCache,
  xlsxSlicerPreserveCurrentSelection);

TXLSXWorkbook.RemoveTimelineCache(ACache: TXLSXTimelineCache; AMode: TXLSXSlicerRemovalMode): Integer 一起暂存连接的筛选、UI、名称与包清理，返回 1 或 -1

xlsxSlicerClearSelection 移除选择；xlsxSlicerPreserveCurrentSelection 只有当日期字段已在每个连接视图的行或列轴上时，才把活动选择保留为整天日期比较

未使用或仅作页字段的日期字段会以原子方式拒绝保留选择的移除；想要这种行为时请使用显式的清除选择移除

导入筛选只有在每个连接、继承的命名空间与精确的持有筛选来源都校验通过后才规范化；不透明的同字段属性或子元素、外部命名空间、外部绑定与不受支持的多 UI 图保留其 XML 并拒绝变更

原生物化把当前 Timeline 选择与报表元数据、单元格一起暂存，只移除精确匹配的已保存持有筛选签名；任意回调限制没有原生 XML 表示，Excel 刷新无法复现

OOXML 保存保留原生关系类型、原始路径与无关扩展；Strict 仅缓存保存被拒绝，ODS 转换报告 Timeline 损失，XLSB 值与样式子集拒绝 Timeline

显式的原生 Slicer 数据状态刷新

function TXLSXSlicerCache.RefreshItemDataStates: Integer; overload;
function TXLSXSlicerCache.RefreshItemDataStates(
  AMaxEvaluationSteps: Integer; ACancelFlag: PBoolean = nil): Integer; overload;

该操作对完整的原生无数据向量求值并暂存，然后在工作簿写入保护下提交；成功返回 1，被拒绝返回 -1，不改变序列化的项标志或选择

它忽略该 Slicer 自身的选择，同时与其他 Slicer 与 Timeline 选择、手动或页筛选、受支持的聚合筛选以及调用方谓词求交集；可用性是各受支持连接视图上的并集

没有符合条件记录的选中历史成员获得原生无数据标志，同时保留其选择；稳定的缓存 ID、原始项线上顺序与无关 XML 保持完好

默认的累计步数上限为 1000000；零表示不限步数，负值被拒绝，FormulaArrayMemoryLimit 以累计方式约束元数据暂存与所有连接视图预览

取消、回调异常或重入、冻结视图、不受支持的绑定、预算耗尽或求值状态变化都会在提交标志前被拒绝；调用方回调对公共模型做出的独立变更仍归调用方，并导致刷新被拒绝

TXLSXSlicerCache.CrossFilter 在变更保护下读写原生的表格型交叉筛选设置；showItemsWithDataAtTop 启用原生的数据优先排序，而不重写项线上顺序

ItemHasData 仍是只读查询；保存不会调用求值器，也不会隐式更新无数据标志，因此需要在保存前刷新原生 UI 状态时请显式调用 RefreshItemDataStates

高级日期筛选语义

TXLSPivotFilter.UseWholeDay 为受支持的日期筛选请求整天日期比较；Timeline 生成的保留选择会使用它，而普通日期筛选保持先前对时刻敏感的行为

周围的刷新与所有权契约参见原生数据透视表输出与只读 Slicer 可用性以及本地缓存与 Slicer 生命周期