コンパイル済みレポート API

The lxReport ユニットは、プレースホルダーと構造的なレポート バンドを一度だけコンパイルし、その後、生成されたワークブック オブジェクトを再スキャンすることなく、境界付きカーソルを通じて呼び出し側が所有するデータを適用します

テーブルとカーソルのコントラクト

実行ごとのデータ セッション

IXLSReportQueryExecutor.ExecuteReadOnly は、1 回のレポート実行の背後にある分離された遅延キャッシュです。

TXLSReportQueryParameter, TXLSReportQueryParameters, and TXLSReportQueryDefinition expose Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameter, and ClearParameters

TXLSReportQueryProvider uses RegisterQuery, RemoveQuery, Clear, and TryGetTable, with Count, Definitions, and MaximumTimeoutMS がホワイトリストとタイムアウト上限を公開します

Per-run data sessions

IXLSReportDataSession は、1 回のレポート実行の背後で動作する分離済みの遅延キャッシュです: 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 は、例外を発生させずに 1 つの名前付き値を検索し、インデックス付きの 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 テーブルのデータ テンプレート行を 1 つ展開します。 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 プロバイダー コントラクトを通じて 1 つのディレクティブ セルをバインドし、解決されたペイロードが書き込まれる前に書き換えできる TXLSReportTransformImageEvent を転送します。解決されたプレースホルダー自体は TXLSReportEvaluatedTarget で、その TXLSReportEvaluatedTargetKind は xretNone、 xretText、 xretValue、 xretFormulaを区別します。 IXLSReportImageCancellation.IsCancellationRequested により、長時間実行のプロバイダーが協調的なキャンセルを監視できます

IXLSReportImageDataProviderV2.GetImage は、安定したワークシート ID、コンパイルされたターゲット、バンド名とテーブル名、論理行とカーソル行、読み取り専用の現在行ビュー、ディレクティブ セルとアンカー セル、EMU 単位のターゲット寸法とオフセット、そして TXLSReportImageRequest を含む IXLSReportImageCancellation

TXLSReportImageResult は TXLSReportImagePayload を保持します。その Kind （TXLSReportImagePayloadKind）が xripMissing、バイト列、またはストリームを選択し、ストリームのライフタイムは TXLSReportImageStreamOwnershipで宣言されます。 xrisoBorrowed のストリームは呼び出し側所有のままで、シーク可能なら位置を復元し、 xrisoTransferred のストリームはちょうど 1 回解放されます。オプションの 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 を発生させます

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 レコードを割り当て、構造化診断ワークシートが 1 枚必要でない限り RuntimeDiagnosticsSheetName は空のままにしてください

回復可能なセルの値と数式はリテラルの [Report error CODE] message テキストになり、セル以外の安全なターゲットは元の値を保持します。オプションの診断ワークシートは、それらの構造化された問題を書き込み済みとしてマークします。ワークシート名と定義名の数式の失敗は、ワークブックの構造を変え得るため、常に停止します

リゾルバーが宣言したデータ エラー、式のゼロ除算、無効な正規表現は、安定したプロバイダーまたは式のカテゴリを使用します。リゾルバーが送出する例外と、コールバック、キャンセル、リソース上限、ロールバック、シリアライズ、セキュリティ、構造の各失敗は、すべて致命的なままです

RunToStream、 RunToFile、 RunToEncryptedFile は、同じ実行とデータ セッションのライフタイム内でシリアライズをステージングし、その後 1 回だけ公開します。致命的、キャンセル、シリアライズ、部分的なストリーム書き込み、出力先置き換えのいずれかの失敗が起きても、完全な以前の出力先が保護され、戻る前に一時ストレージが解放されます

空でない出力ストリームは、ロールバックが元のバイト、サイズ、位置を復元できるよう、読み取り可能・書き込み可能・サイズ変更可能・シーク可能でなければなりません。8 MiB までのスナップショットはメモリに保持され、それより大きいスナップショットは管理された一時ストレージを使用します。コミットが成功すると、ストリームは位置 0 に置かれます

暗号化されていない出力は、生成されたワークブックのソース形式を使用するため、ODS テンプレートは必要なパッケージ メタデータを伴う ODS ストリームまたはファイルを生成します。暗号化出力は引き続き暗号化された Office コンテナを使用します

ImageProvider は元の互換性コントラクトを保持します。 ImageProviderV2、 OnTransformImage、 MaximumImageBytes、 MissingImagePolicy、および ClearImageDirectiveCell により、ランナー、ジェネレーター、範囲バンド、Excel テーブル バンドが、事前コンパイルされた {{#image Key}} ターゲットを直接消費できます。どちらのプロバイダーも指定しない場合、それらのディレクティブ セルは変更されません

AutofitMode （型 TXLSReportAutofitMode）は、すべてのターゲットの実行後に 1 回適用されるワークシート全体のオートフィット（xramNone、 xramRows、 xramColumns、 xramBoth）を選択し、 AutofitAdjustment は余裕係数の追加値です（1.0 = なし、1.1 = 行が 10% 高い）

生成ライフサイクルとテンプレート ソース

TXLSReportLifecyclePhase はテンプレート読み取り、ワークブック生成、ワークシート生成の境界を特定し、 TXLSReportLifecycleOutcome は開始、完了、キャンセル、失敗のコールバックを区別します

TXLSReportLifecycleContext は、アクティブなワークブックとワークシート、安定したワークシート ID、元と現在の座標、読み取り専用の 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 を提供します

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 には、ランナーを解放する前に completed-with-errors 状態と問題数を検証する、完全に実行可能なバージョンが含まれています

関連項目

• 高度なワークブック ワークフロー
• TXLSXWorkbook
• TXLSPaginationModel