Compiled-Reporting-API

Die Unit lxReport kompiliert Platzhalter und strukturelle Report-Bänder einmal und wendet dann Daten in Besitz des Aufrufers über begrenzte Cursor an, ohne die erzeugten Arbeitsmappenobjekte erneut durchsuchen zu müssen

Tabellen- und Cursor-Verträge

Kontrollierte Abfrageanbieter

IXLSReportQueryExecutor.ExecuteReadOnly hält die Abfrageausführung in der Hand des Hosts und akzeptiert nur Definitionen, die vom Anwendungscode registriert wurden

TXLSReportQueryParameter, TXLSReportQueryParametersund TXLSReportQueryDefinition legen Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameterund ClearParameters

TXLSReportQueryProvider verwendet RegisterQuery, RemoveQuery, Clearund TryGetTable, während Count, Definitionsund MaximumTimeoutMS die Whitelist und die Timeout-Obergrenze offenlegen

Datensitzungen pro Lauf

IXLSReportDataSession ist der isolierte verzögerte Cache hinter einem Report-Lauf: DeclareRequest registriert eine TXLSReportDataRequest (Art TXLSReportDataRequestKind: xrdrkNamed oder xrdrkUser), deren TXLSReportDataSource (Art TXLSReportDataSourceKind: unspezifiziert, Zelle, Bereichsband, Tabellenband oder Ausdruck) und TXLSReportDataParameter -Liste die Quelle und ihre Werte beschreiben und deren RunControl das IXLSReportRunControl -Abbruchhandle des Hosts ist; HasResolver prüft einen Provider-Schlüssel, TryGetTable und RequireTable lesen zwischengespeicherte Aliasse, TryResolveTable und RequireResolvedTable lösen auf Bedarf in ein TXLSReportDataResolveResult auf (Status TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFoundoder xrdrsDataError), und TryGetState meldet einen TXLSReportDataSessionState aus Laden, aufgelöst, nicht gefunden oder Datenfehler, während CachedAliasCount und ResolvedAliasCount die Sitzungsgröße offenlegen

IXLSReportDataView.TryGetValue schlägt einen einzelnen benannten Wert nach, ohne eine Exception auszulösen, und ergänzt damit die indizierten Accessoren Count, Namesund Values accessors

Relationen und verzögerte Tabellen-Kombinatoren

TXLSReportRowIndexes und TXLSReportRelationIndex behalten Kind-Zeilennummern in Buckets mit zusammengesetzten Schlüsseln; verwenden Sie FindChildRows oder CreateChildCursor und prüfen Sie BucketCount oder IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregateund TXLSReportJoinKind konfigurieren TXLSReportTableFactory, deren Zeilenfilter über TXLSReportFilterOperator vergleichen (xrfoEqual, xrfoNotEqual, xrfoGreater, xrfoGreaterEqual, xrfoLess, xrfoLessEqual, xrfoContains, xrfoStartsWith, xrfoEndsWith)

Benannte und explizite Bereichs-Bänder

TXLSReportBandKind wählt die Zeilen-, Spalten- oder Cross-Tab-Erweiterung, und TXLSReportBandState meldet den Lebenszykluszustand bereit, läuft, abgeschlossen, mit Fehlern abgeschlossen, abgebrochen oder fehlgeschlagen

TXLSCompiledReportBand nimmt einen definierten Namen mit exaktem Gültigkeitsbereich oder CreateForRangeentgegen und expandiert dann über die Run -Überladungen; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCountund State legen den kompilierten Plan offen

EmptyBandPolicy (Typ TXLSEmptyBandPolicy) steuert, was das Band bei leerem Datensatz mit seinen Vorlagenzeilen macht — xreKeepTemplate lässt die Zeilen unangetastet, xreClearTemplate räumt die Bandzellen inklusive Platzhalter, und xreDeleteTemplate löscht die Vorlagenzeilen — und DeleteLastRow entfernt die letzten BandHeight Zeilen des expandierten Blocks, nachdem seine Kopien gelandet sind, sodass nachlaufende X-Bereichs-Trennzeilen entfallen

FixedBand lässt Zeilenbänder die Zeilen unterhalb der Vorlage überschreiben, statt neue einzufügen, sodass umgebender Inhalt an fester Position bleibt

Zeilen- und Spaltenbereichs-Bänder klonen Threaded-Comment-Conversations, wenn jede Wurzel und jede Antwort zum Vorlagenbereich gehört; Text- und Anzeigenamen-Platzhalter werden pro Datensatz ausgewertet, kopierte Kommentare erhalten neue Kennungen und neu zugeordnete Eltern-Kennungen, und vorhandene Personen-Datensätze der Arbeitsmappe werden wiederverwendet

Die Kompilierung weist Conversations ab, die über die Vorlagengrenze hinweg aufgeteilt sind, sowie fehlende Eltern, doppelte Kennungen und invalide Zellanker, bevor die Expansion beginnt; Anker-Überlauf wird vor der Arbeitsblattmutation geprüft, und ein fehlgeschlagener oder abgebrochener Lauf entfernt erzeugte Conversations, während der Vorlagenzustand wiederhergestellt wird

TXLSCompiledTableReportBand.Run erweitert eine Datenvorlagenzeile einer Excel-Tabelle und bewahrt dabei die Tabellenmetadaten; prüfen Sie TableName, Sheet, SheetIndex, ExcelTable, TemplateRowund Stateund konfigurieren Sie dieselben V2-Bildeigenschaften, die Bereichsbänder anbieten

Bereichs- und Excel-Tabellenbänder teilen ErrorMode, StrictDataAccess, RuntimeLimitsund unveränderliche LastResult -Snapshots; xremWriteAndContinue schreibt nur explizite wiederherstellbare Zellfehler als literale Diagnosen, merkt sich die Quell- BandInputRow und die tatsächlichen Ausgabekoordinaten und fährt mit späteren Zielen und Zeilen fort, während strukturelle, Abbruch-, Ressourcenlimit-, Callback- und Rollback-Fehler fatal bleiben

TXLSCompiledSheetReportBand.Run erstellt Tabellenblätter pro Datensatz mithilfe von NameColumn, NamePrefixund DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run erstellt Fortsetzungsblätter mit NamePrefix und DeleteTemplateAfterRun

Vorlagen für die gesamte Arbeitsmappe

TXLSReportTemplateTarget und TXLSReportTemplateTargets wählen Zellen, Kommentare, Hyperlinks, Formen, Kopf- und Fußzeilen, Blattnamen, definierte Namen und Dokumenteigenschaften

TXLSCompiledReportTemplate.Compile erfasst Ziele und Ausdrücke, Analyze liefert adressierte TXLSReportIssues, die Run -Überladungen wenden Werte an, und WriteDiagnostics schreibt Issues in ein Arbeitsblatt; TargetAreas, TargetCountund UserTableCount beschreiben die kompilierte Oberfläche und die registrierten Benutzertabellen

ProcessStructuralDirectives (Standard True) lässt einen Vorlagen- Run die strukturellen Direktiven {{#delete}} und {{#format}} ausführen, nachdem die Wertziele angewendet wurden — der dahinter liegende TXLSReportDirectiveProcessor parst die Bereiche, wendet sie an und meldet über AppliedCount , wie viele er behandelt hat — und CreateEncrypted öffnet eine verschlüsselte Vorlage mit ihrem Passwort und kompiliert sie, während die Arbeitsmappe über die Eigenschaft Workbook erreichbar bleibt

TXLSReportIssueKind, TXLSReportIssueund TXLSReportIssues identifizieren fehlerhafte, fehlende, ungültige, unbekannte oder zyklische Platzhalterinhalte mit Ziel- und Zellkoordinaten

Includes, Bilder und Formatierung

IXLSReportIncludeResolver.Resolve liefert benannte Fragmente, und ihr Flag Immutable erlaubt sichere Wiederverwendung; TXLSReportIncludeLibrary bietet Add, Remove, Clear, Freeze, Resolve, Countund Immutable

IXLSReportImageProvider.TryGetImage liefert einen über TXLSReportImageValue konfigurierten TXLSReportImageFit; TXLSReportMissingImagePolicy steuert fehlende Ressourcen, während TXLSReportImageBinder.Apply, ApplyTarget, MissingPolicyund ClearDirectiveCell exakte Bilddirektiven aktualisieren

TXLSReportImageBinder.ApplyTargetV2 bindet eine Direktive-Zelle über den V2-Provider-Vertrag und leitet ein TXLSReportTransformImageEvent weiter, das die aufgelöste Payload umschreiben kann, bevor sie landet; der aufgelöste Platzhalter selbst ist ein TXLSReportEvaluatedTarget , dessen TXLSReportEvaluatedTargetKind distinguishes xretNone, xretText, xretValueund xretFormulaunterscheidet; IXLSReportImageCancellation.IsCancellationRequested lässt langlebige Provider einen kooperativen Abbruch beobachten

IXLSReportImageDataProviderV2.GetImage empfängt eine TXLSReportImageRequest mit stabiler Arbeitsblatt-Identität, kompiliertem Ziel, Band- und Tabellennamen, logischen und Cursor-Zeilen, einer schreibgeschützten Ansicht der aktuellen Zeile, Direktiv- und Ankerzellen, Zielabmessungen und -Offsets in EMU sowie IXLSReportImageCancellation

TXLSReportImageResult trägt eine TXLSReportImagePayload , deren Kind (TXLSReportImagePayloadKind) xripMissing, Bytes oder einen Stream wählt, wobei die Lebensdauer des Streams über TXLSReportImageStreamOwnershipdeklariert wird: xrisoBorrowed -Streams bleiben in Besitz des Aufrufers und stellen ihre Position wieder her, wenn sie seekable sind, während xrisoTransferred -Streams genau einmal freigegeben werden; optionale SourceWidth, SourceHeight, SourceDpiXund SourceDpiY behaupten oder überschreiben die physische Quellgeometrie

xrifNatural verwendet die physische Quellgröße, xrifContain skaliert und zentriert innerhalb der Zielbox, xrifCover füllt die Box mit symmetrischem Beschnitt der Quelle, und xrifStretch füllt sie ohne Erhalt des Seitenverhältnisses; die Geometrie von PNG, JPEG, GIF, BMP, EMF und WMF wird aus begrenzten Headern gelesen, ohne Pixel zu dekodieren

OnTransformImage läuft, nachdem die Provider-Daten gesnapshotet wurden und bevor das Arbeitsblatt verändert wird; MaximumImageBytes steht standardmäßig auf 64 MiB, und Payload-Signaturen, Geometrie-Header, Dimensions- und DPI-Paare, Rasterseiten- und Pixellimits, Anker sowie Gitterkoordinaten werden vor dem Binden validiert

TXLSXImage.OffsetXEMU und OffsetYEMU bewahren die Position eines Bilds in seiner Zelle oder seinem absoluten Anker über XLSX- und ODS-Roundtrips hinweg

TXLSReportDynamicFormat und TXLSReportFormatEvent ermöglichen einem Runner, Zahlenformate, Zeilenhöhen und Spaltenbreiten pro Ziel anzuwenden

Wiederverwendbare Ausführung

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgressund TXLSReportRunProgressEvent beschreiben Fortschritts- und Abbruchgrenzen

TXLSCompiledReportRunner legt Run, RunToStream, RunToFile, RunToEncryptedFileund Canceloffen, mit ReportTemplate, State, Progress, OnProgressund OnFormat zur Steuerung der wiederverwendbaren Ausführung; fehlgeschlagene Validierung wirft EXLSReportData , bevor deterministisch geschrieben wird

ErrorMode (Typ TXLSReportErrorMode) steht standardmäßig auf xremStop; xremWriteAndContinue behandelt nur explizite EXLSReportRecoverableData -Fehler und DataError -Ergebnisse von Resolvern, zeichnet geordnete unveränderliche Issues in LastResult auf (ein IXLSReportRunResult mit State, AppliedCount, IssueCount, indizierten Issuessowie FailureClassName / FailureMessage eines fatalen Fehlers), deren TXLSReportRuntimeIssue -Snapshots ihre Category (ein TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProvideroder xrricExpression) offenlegen und TargetIndex, SheetName, Colmelden sowie ob das Issue bereits WasWritten in die Ausgabe geschrieben wurde, und endet als xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults erlaubt 100.000 vorgehaltene Issues, 512 Zeichen pro bereinigter Meldung und 16 MiB Issue-Speicher; weisen Sie vor einem Lauf einen positiven benutzerdefinierten RuntimeLimits -Datensatz zu und lassen Sie RuntimeDiagnosticsSheetName leer, sofern kein einzelnes strukturiertes Diagnose-Arbeitsblatt benötigt wird

Wiederherstellbare Zellwerte und Formeln werden zu literalem [Report error CODE] message -Text, sichere Nicht-Zell-Ziele behalten ihren ursprünglichen Wert, und ein optionales Diagnose-Arbeitsblatt markiert diese strukturierten Issues als geschrieben; Fehler bei Arbeitsblattnamen und Formeln definierter Namen brechen immer ab, weil sie die Arbeitsmappenstruktur ändern können

Resolver-deklarierte Datenfehler, Division durch null in Ausdrücken und ungültige reguläre Ausdrücke verwenden stabile Provider- oder Ausdruckskategorien; geworfene Resolver-Exceptions sowie sämtliche Callback-, Abbruch-, Ressourcenlimit-, Rollback-, Serialisierungs-, Sicherheits- und Strukturfehler bleiben fatal

RunToStream, RunToFileund RunToEncryptedFile stufen die Serialisierung innerhalb derselben Lauf- und Datensitzungs-Lebensdauer und veröffentlichen dann einmalig; jeder fatale, abgebrochene, Serialisierungs-, partielle Stream-Schreib- oder Zielersetzungs-Fehler bewahrt das vollständige frühere Ziel und gibt temporären Speicher frei, bevor zurückgegeben wird

Ein nichtleerer Ausgabestream muss lesbar, schreibbar, größenänderbar und seekable sein, damit ein Rollback ursprüngliche Bytes, Größe und Position wiederherstellen kann; Snapshots bis 8 MiB bleiben im Speicher, größer nutzen verwaltetes temporäres Storage, während ein erfolgreicher Commit den Stream an Position null zurücklässt

Unverschlüsselte Ausgabe verwendet das Quellformat der erzeugten Arbeitsmappe, sodass eine ODS-Vorlage einen ODS-Stream oder eine ODS-Datei mit ihrer benötigten Paketmetadaten erzeugt; verschlüsselte Ausgabe nutzt weiterhin den verschlüsselten Office-Container

ImageProvider bewahrt den ursprünglichen Kompatibilitätsvertrag; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicyund ClearImageDirectiveCell lassen Runner, Generator, Bereichsband oder Excel-Tabellenband vorcompilierte {{#image Key}} -Ziele direkt konsumieren; lässt man beide Provider weg, bleiben diese Direktive-Zellen unverändert

AutofitMode (Typ TXLSReportAutofitMode) wählt eine AutoFit über das ganze Blatt (xramNone, xramRows, xramColumnsoder xramBoth), das einmal nach allen Zielen angewendet wird, und AutofitAdjustment ist ein zusätzlicher Luftfaktor (1.0 = keiner, 1.1 = 10 % höhere Zeilen)

Generierungslebenszyklus und Vorlagenquellen

TXLSReportLifecyclePhase identifiziert die Grenzen Vorlagen-Lesen, Arbeitsmappen-Generierung und Arbeitsblatt-Generierung, während TXLSReportLifecycleOutcome betretene, abgeschlossene, abgebrochene und fehlgeschlagene Callbacks unterscheidet

TXLSReportLifecycleContext liefert die aktive Arbeitsmappe und das aktive Arbeitsblatt, stabile Arbeitsblatt-Identität, ursprüngliche und aktuelle Koordinaten, eine schreibgeschützte IXLSReportDataView, Zielanzahl und Details zum ersten Fehler; jedes betretene Before-Ereignis erhält ein gepaartes After-Ereignis, selbst wenn die Generierung abgebrochen wird oder fehlschlägt

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheetund AfterGenerateSheet beobachten einen eingefrorenen Satz ursprünglicher Arbeitsblätter; callback-getriebene Strukturänderungen lösen eine Kompilierungs-Auffrischung aus, ohne neu erzeugte Blätter in den aktuellen Lauf aufzunehmen

TXLSReportGenerator nimmt eine Arbeitsmappe, einen Dateinamen, einen Stream in Besitz des Aufrufers oder eine verschlüsselte Datei entgegen und ergänzt BeforeReadTemplate plus AfterReadTemplate zu den Generierungsereignissen; TXLSReportModificationMode wählt kompatible In-place-Mutation oder isolierte Atomic-Clone-Generierung. Schreibgeschützte SourceKind (Typ TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStreamoder xrtsEncryptedFile) und TemplateWorkbook melden die konfigurierte Vorlagenquelle, während ModificationMode und IncludeResolver vor einem Lauf setzbar sind

Datei- und Stream-Vorlagen stehen standardmäßig auf xrmAtomicClone; seekable Eingabe-Streams stellen ihre ursprüngliche Position wieder her, Forward-only-Streams werden in begrenzten Blöcken konsumiert, Streams des Aufrufers bleiben offen, und Ausgabeströme oder -dateien werden erst nach erfolgreichem Abschluss ersetzt

Planung, Prüfung und Migration

TXLSReportPaginationPlanner bietet KeepTogether-, SplitRows-, MergeSimilar- und BalanceColumns -Pläne für feste Fußzeilen und ausgewogene Ausgabe

TXLSReportTemplateChecker bietet Check, CheckBandund CheckTableBand; TXLSReportTemplateMigrator bietet MigrateText und MigrateWorkbook für unterstützte Legacy-Platzhalterformen

Delphi-Beispiel

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-Beispiel

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;

Die Delphi-Demo FeatureShowcase und die C++Builder-Demo XlsxFeatureGallery enthalten vollständig lauffähige Varianten, die den Zustand mit-Fehlern-abgeschlossen und die Issue-Anzahl prüfen, bevor der Runner freigegeben wird

Siehe auch

• Erweiterte Arbeitsmappen-Workflows
• TXLSXWorkbook
• TXLSPaginationModel