編譯式報表 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 範圍分隔列收合

FixedBand 讓資料列範圍帶改為覆寫範本下方的資料列而不是插入新列，讓周圍內容保持在固定位置

當每個根討論串與回覆都屬於範本範圍時，列與欄範圍帶會複製對話串註解對話；文字與顯示名稱預留位置會針對每筆記錄評估，複製的註解取得新的識別碼與重新映射的父識別碼，既有的活頁簿人員記錄則被重用

編譯會在展開前拒絕跨範本邊界的對話、缺漏的父項、重複的識別碼與無效的儲存格錨點；錨點溢出會在工作表變更前檢查，失敗或取消的執行會移除產生的對話並還原範本狀態

TXLSCompiledTableReportBand.Run 展開一列 Excel 資料表資料範本列，同時保留資料表中繼資料；檢查 TableName、 Sheet、 SheetIndex、 ExcelTable、 TemplateRow與 State，並設定與範圍帶相同的 V2 影像屬性

範圍帶與 Excel 資料表帶共用 ErrorMode、 StrictDataAccess、 RuntimeLimits與不可變的 LastResult 快照； xremWriteAndContinue 只把明確的可復原儲存格失敗寫成 literal 診斷文字，記錄來源 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 的來回之間保留影像在儲存格或絕對錨點內的位置

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 保持空白

可復原的儲存格值與公式會變成 literal 的 [Report error CODE] message 文字，安全的非儲存格目標保留原值，選擇性的診斷工作表會把那些結構化問題標記為已寫入；工作表名稱與定義名稱公式的失敗一律停止，因為它們可能改變活頁簿結構

解析器宣告的資料錯誤、運算式除以零與無效的正規表示式，使用穩定的提供者或運算式分類；解析器擲出的例外，以及所有回呼、取消、資源限制、復原、序列化、安全性與結構性失敗，都仍視為致命

RunToStream、 RunToFile與 RunToEncryptedFile 會在同一個執行與資料工作階段生命週期內暫存序列化，然後一次發布；任何致命、取消、序列化、部分串流寫入或目的地取代失敗，都會保留完整的前一版目的地，並在傳回前釋放暫存儲存

非空的輸出串流必須可讀、可寫、可調整大小且可定位，讓復原可以還原它原本的位元組、大小與位置；8 MiB 以下的快照留在記憶體中，更大的快照使用受管理的暫存儲存，成功提交後串流會定位在 0

未加密的輸出使用所產生活頁簿的來源格式，所以 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