编译式报表 API

The lxReport 单元一次性编译占位符和结构化的报表带区，然后通过有界游标应用调用方拥有的数据，而无需重新扫描生成的工作簿对象

表与游标约定

受控的查询提供程序

IXLSReportQueryExecutor.ExecuteReadOnly 保持查询执行由宿主拥有，并且只接受由应用程序代码注册的定义

TXLSReportQueryParameter、 TXLSReportQueryParameters和 TXLSReportQueryDefinition 暴露 Name、 CommandText、 TimeoutMS、 ParameterCount、 Parameters、 SetParameter和 ClearParameters

TXLSReportQueryProvider 使用 RegisterQuery、 RemoveQuery、 Clear和 TryGetTable，其中 Count、 Definitions和 MaximumTimeoutMS 暴露白名单和超时上限

按次运行的数据会话

IXLSReportDataSession 是一次报表运行背后的隔离惰性缓存： DeclareRequest 注册一个 TXLSReportDataRequest （类型为 TXLSReportDataRequestKind： xrdrkNamed 或 xrdrkUser），其 TXLSReportDataSource （类型为 TXLSReportDataSourceKind：未指定、单元格、区域带区、表格带区或表达式）和 TXLSReportDataParameter 列表描述数据源及其取值，其 RunControl 则是宿主的 IXLSReportRunControl 取消句柄； HasResolver 测试提供程序键， TryGetTable 和 RequireTable 读取缓存的别名， TryResolveTable 和 RequireResolvedTable 按需解析并产出 TXLSReportDataResolveResult （状态为 TXLSReportDataResolveStatus： xrdrsUnhandled、 xrdrsResolved、 xrdrsNotFound或 xrdrsDataError）， TryGetState 报告加载中、已解析、未找到或数据错误的 TXLSReportDataSessionState ，而 CachedAliasCount 和 ResolvedAliasCount 暴露会话规模

IXLSReportDataView.TryGetValue 查找单个命名值而不抛异常，与按索引访问的 Count、 Names和 Values 访问器互补

关系与惰性表组合器

TXLSReportRowIndexes 和 TXLSReportRelationIndex 在复合键桶中保留子行号；使用 FindChildRows 或 CreateChildCursor ，并检查 BucketCount 或 IndexedRowCount

TXLSReportAggregateKind、 TXLSReportAggregate和 TXLSReportJoinKind 配置 TXLSReportTableFactory，其行过滤器通过 TXLSReportFilterOperator （xrfoEqual、 xrfoNotEqual、 xrfoGreater、 xrfoGreaterEqual、 xrfoLess、 xrfoLessEqual、 xrfoContains、 xrfoStartsWith、 xrfoEndsWith）进行比较

命名与显式区域带区

TXLSReportBandKind 选择行、列或交叉表展开， TXLSReportBandState 报告就绪、运行中、已完成、已完成但带错误、已取消或失败的生命周期状态

TXLSCompiledReportBand 接受精确范围的已定义名称或 CreateForRange，然后通过 Run 重载展开； DefinedName、 ScopeSheetIndex、 Kind、 Sheet、 SheetIndex、 FirstRow、 FirstCol、 LastRow、 LastCol、 TargetCount和 State 暴露编译计划

EmptyBandPolicy （类型 TXLSEmptyBandPolicy）控制数据集为空时带区如何处理自己的模板行—— xreKeepTemplate 原样保留这些行， xreClearTemplate 清空带区单元格（包括占位符）， xreDeleteTemplate 删除模板行； DeleteLastRow 会在展开块的副本落地后移除末尾的 BandHeight 行，从而收拢尾部的 X-range 分隔行

FixedBand 让行带区直接覆盖模板下方的行而不是插入新行，使周围内容保持在固定位置

当每个根批注和回复都属于模板范围时，行和列范围带区会克隆会话式批注线程；文本和显示名占位符按每条记录求值，复制的批注获得新的标识符并重映射父标识符，工作簿既有的个人记录会被复用

编译会在展开前拒绝跨模板边界拆分的会话、缺失的父批注、重复的标识符和无效的单元格锚点；锚点溢出在工作表变更前检查，失败或取消的运行会移除生成的会话并恢复模板状态

TXLSCompiledTableReportBand.Run 展开一个 Excel 表格数据模板行，同时保留表格元数据；检查 TableName、 Sheet、 SheetIndex、 ExcelTable、 TemplateRow和 State，并配置与区域带区相同的 V2 图像属性

区域带区和 Excel 表格带区共享 ErrorMode、 StrictDataAccess、 RuntimeLimits和不可变的 LastResult 快照； xremWriteAndContinue 只把显式的可恢复单元格失败写成字面诊断文本，记录来源 BandInputRow 和实际输出坐标，并继续处理后续目标和行，而结构性、取消、资源限制、回调和回滚失败仍然是致命的

TXLSCompiledSheetReportBand.Run 使用 NameColumn、 NamePrefix和 DeleteTemplateAfterRun创建逐记录工作表； TXLSCompiledOverflowReportBand.Run 使用 NamePrefix 和 DeleteTemplateAfterRun

整个工作簿的模板

TXLSReportTemplateTarget 和 TXLSReportTemplateTargets 选择单元格、批注、超链接、形状、页眉和页脚、工作表名称、已定义名称和文档属性

TXLSCompiledReportTemplate.Compile 捕获目标和表达式， Analyze 返回已寻址的 TXLSReportIssues， Run 重载应用值， WriteDiagnostics 将问题写入工作表； TargetAreas、 TargetCount和 UserTableCount 描述编译表面和已注册的用户表格

ProcessStructuralDirectives （默认 True）让模板 Run 在应用完值目标之后执行结构化的 {{#delete}} 和 {{#format}} 指令——背后的 TXLSReportDirectiveProcessor 负责解析范围、应用它们，并通过 AppliedCount 报告处理了多少条—— CreateEncrypted 则用密码打开加密模板并编译，同时保证工作簿仍可通过 Workbook 属性访问

TXLSReportIssueKind、 TXLSReportIssue和 TXLSReportIssues 通过目标和单元格坐标识别格式错误、缺失、无效、未知或循环的占位符内容

包含、图像和格式

IXLSReportIncludeResolver.Resolve 提供命名片段，其 Immutable 标志允许安全复用； TXLSReportIncludeLibrary 提供 Add、 Remove、 Clear、 Freeze、 Resolve、 Count和 Immutable

IXLSReportImageProvider.TryGetImage 返回由 TXLSReportImageValue 配置的 TXLSReportImageFit； TXLSReportMissingImagePolicy 控制缺失资源，而 TXLSReportImageBinder.Apply、 ApplyTarget、 MissingPolicy和 ClearDirectiveCell 更新精确的图像指令

TXLSReportImageBinder.ApplyTargetV2 通过 V2 提供程序约定绑定单个指令单元格，并转发一个 TXLSReportTransformImageEvent ，允许在解析出的负载落地前重写它；被解析的占位符本身是一个 TXLSReportEvaluatedTarget ，其 TXLSReportEvaluatedTargetKind 区分 xretNone、 xretText、 xretValue和 xretFormula； IXLSReportImageCancellation.IsCancellationRequested 让长时间运行的提供程序能够观察协作式取消

IXLSReportImageDataProviderV2.GetImage 接收 TXLSReportImageRequest ，其中包含稳定的工作表标识、编译后的目标、带区和表格名称、逻辑行与游标行、只读的当前行视图、指令单元格与锚点单元格、以 EMU 表示的目标尺寸和偏移，以及 IXLSReportImageCancellation

TXLSReportImageResult 携带一个 TXLSReportImagePayload ，其 Kind （TXLSReportImagePayloadKind）选择 xripMissing、字节数组或流；流的生命周期由 TXLSReportImageStreamOwnership声明： xrisoBorrowed 流仍归调用方所有，且在支持定位时恢复原位置， xrisoTransferred 流则恰好释放一次；可选的 SourceWidth、 SourceHeight、 SourceDpiX和 SourceDpiY 用于断言或覆盖物理源尺寸

xrifNatural 使用源图像的物理尺寸， xrifContain 在目标框内等比缩放并居中， xrifCover 通过对称裁剪源图像填满目标框， xrifStretch 填满但不保持宽高比；PNG、JPEG、GIF、BMP、EMF 和 WMF 的几何信息直接从有界头部读取，不解码像素

OnTransformImage 在提供程序数据被快照之后、工作表被修改之前运行； MaximumImageBytes 默认 64 MiB，负载签名、几何头部、尺寸与 DPI 对、光栅边长与像素上限、锚点以及网格坐标都会在绑定前完成校验

TXLSXImage.OffsetXEMU 和 OffsetYEMU 让图像在单元格内或绝对锚点中的位置在 XLSX 与 ODS Roundtrip 之间保持不变

TXLSReportDynamicFormat 和 TXLSReportFormatEvent 让运行器为每个目标应用数字格式、行高和列宽

可重用的执行

TXLSReportRunPhase、 TXLSReportRunState、 TXLSReportRunProgress和 TXLSReportRunProgressEvent 描述进度和取消边界

TXLSCompiledReportRunner 暴露 Run、 RunToStream、 RunToFile、 RunToEncryptedFile和 Cancel，其中 ReportTemplate、 State、 Progress、 OnProgress和 OnFormat 控制可重用的执行；失败的验证在确定性写入之前抛出 EXLSReportData before deterministic writes

ErrorMode （类型 TXLSReportErrorMode）默认为 xremStop； xremWriteAndContinue 只处理显式的 EXLSReportRecoverableData 失败和解析器的 DataError 结果，把有序的不可变问题记录到 LastResult （一个 IXLSReportRunResult ，暴露 State、 AppliedCount、 IssueCount、按索引访问的 Issues，以及致命失败的 FailureClassName / FailureMessage ），其中的 TXLSReportRuntimeIssue 快照暴露 Category （ TXLSReportRuntimeIssueCategory： xrricDataAccess、 xrricProvider或 xrricExpression），并报告 TargetIndex、 SheetName、 Col以及该问题是否已被 WasWritten 写入输出，最终以 xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults 允许保留 100,000 条问题、每条净化消息 512 个字符、16 MiB 的问题内存；请在运行前赋一个正的自定义 RuntimeLimits 记录，除非确实需要一张结构化诊断工作表，否则让 RuntimeDiagnosticsSheetName 保持为空

可恢复的单元格值和公式会变成字面的 [Report error CODE] message 文本，安全的非单元格目标保留原值，可选的诊断工作表会把这些结构化问题标记为已写入；工作表名称和已定义名称公式的失败总是中止，因为它们可能改变工作簿结构

解析器声明的数据错误、表达式除以零和无效正则使用稳定的提供程序或表达式类别；解析器抛出的异常以及所有回调、取消、资源限制、回滚、序列化、安全和结构性失败仍然是致命的

RunToStream、 RunToFile和 RunToEncryptedFile 把序列化安排在同一次运行和数据会话生命周期内，然后一次性发布；任何致命、取消、序列化、部分流写入或目标替换失败都会保留目标此前的完整内容，并在返回前释放临时存储

非空输出流必须可读、可写、可扩容、可定位，这样回滚才能恢复其原始字节、大小和位置；不超过 8 MiB 的快照驻留内存，更大的快照使用受管的临时存储，成功提交后流会定位回起始处

未加密输出沿用生成工作簿的源格式，因此 ODS 模板产出带必需包元数据的 ODS 流或文件；加密输出继续使用加密的 Office 容器

ImageProvider 保留原有的兼容约定； ImageProviderV2、 OnTransformImage、 MaximumImageBytes、 MissingImagePolicy和 ClearImageDirectiveCell 让运行器、生成器、区域带区或 Excel 表格带区直接消费预编译的 {{#image Key}} 目标；两个提供程序都不提供时，这些指令单元格保持不变

AutofitMode （类型 TXLSReportAutofitMode）选择整表自适应（xramNone、 xramRows、 xramColumns或 xramBoth），在所有目标运行完后应用一次； AutofitAdjustment 是额外的高度余量系数（1.0 = 不调整，1.1 = 行高增加 10%）

生成生命周期与模板来源

TXLSReportLifecyclePhase 标识模板读取、工作簿生成和工作表生成边界， TXLSReportLifecycleOutcome 区分进入、完成、取消和失败的回调

TXLSReportLifecycleContext 提供活动工作簿和工作表、稳定的工作表标识、原始与当前坐标、只读的 IXLSReportDataView、目标数量以及首次失败细节；即使生成被取消或失败，每个进入的 before 事件也都有配对的 after 事件

TXLSCompiledReportRunner.BeforeGenerateWorkbook、 AfterGenerateWorkbook、 BeforeGenerateSheet和 AfterGenerateSheet 观察一组冻结的原始工作表；回调驱动的结构变化会触发编译刷新，但不会把新建的工作表加入当前运行

TXLSReportGenerator 接受工作簿、文件名、调用方拥有的流或加密文件，并在生成事件中增加 BeforeReadTemplate 和 AfterReadTemplate ； TXLSReportModificationMode 选择兼容的原地修改或隔离的原子克隆生成。只读的 SourceKind （类型 TXLSReportTemplateSourceKind： xrtsWorkbook、 xrtsFile、 xrtsStream或 xrtsEncryptedFile）和 TemplateWorkbook 报告配置的模板来源， ModificationMode 和 IncludeResolver 可在运行前设置

文件和流模板默认 xrmAtomicClone；可定位的输入流会恢复原位置，只进流按有界块消费，调用方的流保持打开，输出流或文件只在整个运行成功完成后才被替换

规划、检查和迁移

TXLSReportPaginationPlanner 为固定页脚和均衡输出提供 KeepTogether、 SplitRows、 MergeSimilar和 BalanceColumns 计划

TXLSReportTemplateChecker 提供 Check、 CheckBand和 CheckTableBand； TXLSReportTemplateMigrator 为支持的旧版占位符形式提供 MigrateText 和 MigrateWorkbook for supported legacy placeholder forms

Delphi 示例

Context := TXLSReportDataContext.Create;
Table := TXLSReportMemoryTable.Create('Orders', ['Customer', 'Amount']);
Table.AddRow(['A. Datum', 1200]);
Context.RegisterTable(Table);
Template := TXLSCompiledReportTemplate.Create(Workbook);
Template.DataContext := Context;
Runner := TXLSCompiledReportRunner.Create(Template);
try
  Runner.StrictDataAccess := True;
  Runner.ErrorMode := xremWriteAndContinue;
  Runner.RuntimeDiagnosticsSheetName := 'Report Diagnostics';
  Runner.RunToFile(Values, OutputFileName);
  RunResult := Runner.LastResult;
finally
  Runner.Free;
  Template.Free;
  Context.Free;
end;

C++Builder 示例

Lxreport::TXLSReportMemoryTable *tableObject =
  new Lxreport::TXLSReportMemoryTable(L"Orders", columns, 1);
Lxreport::_di_IXLSReportTable table;
tableObject->GetInterface(table);
tableObject->AddRow(row, 1);
context->RegisterTable(table);

Lxreport::TXLSCompiledReportTemplate *reportTemplate =
  new Lxreport::TXLSCompiledReportTemplate(workbook);
reportTemplate->DataContext = context;
Lxreport::TXLSCompiledReportRunner *runner =
  new Lxreport::TXLSCompiledReportRunner(reportTemplate);
runner->StrictDataAccess = true;
runner->ErrorMode = Lxreport::xremWriteAndContinue;
runner->RuntimeDiagnosticsSheetName = L"Report Diagnostics";
runner->RunToFile(values, outputFileName);
Lxreport::_di_IXLSReportRunResult runResult = runner->LastResult;

Delphi 的 FeatureShowcase 和 C++Builder 的 XlsxFeatureGallery 示例包含完整可运行的版本，会在释放运行器之前验证"已完成但带错误"的状态和问题数量

另请参阅

• 高级工作簿工作流
• TXLSXWorkbook
• TXLSPaginationModel