Gecompileerde rapportage-API

De eenheid lxReport compileert plaatshouders en structurele rapportbanden één keer en past daarna door de aanroeper beheerde gegevens toe via begrensde cursors, zonder gegenereerde werkmapobjecten opnieuw te scannen

Tabellen- en cursorcontracten

Beheerde queryproviders

IXLSReportQueryExecutor.ExecuteReadOnly houdt de query-uitvoering in handen van de host en accepteert alleen definities die door de toepassingscode zijn geregistreerd

TXLSReportQueryParameter, TXLSReportQueryParametersen TXLSReportQueryDefinition stellen Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameteren ClearParameters

TXLSReportQueryProvider gebruikt RegisterQuery, RemoveQuery, Clearen TryGetTable, waarbij Count, Definitionsen MaximumTimeoutMS de whitelist en de timeoutlimiet blootleggen

Per-run datasessies

IXLSReportDataSession is de geïsoleerde luie cache achter één rapportrun: DeclareRequest registreert een TXLSReportDataRequest (soort TXLSReportDataRequestKind: xrdrkNamed of xrdrkUser) waarvan de TXLSReportDataSource (soort TXLSReportDataSourceKind: unspecified, cel, range band, table band of expressie) en de TXLSReportDataParameter -lijst de bron en zijn waarden beschrijven, en waarvan RunControl de annuleringshandle IXLSReportRunControl van de host is; HasResolver toetst een providersleutel, TryGetTable en RequireTable lezen gecachte aliassen, TryResolveTable en RequireResolvedTable herleiden op vraag naar een TXLSReportDataResolveResult (status TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFoundof xrdrsDataError), en TryGetState rapporteert een TXLSReportDataSessionState van loading, resolved, not found of data error, terwijl CachedAliasCount en ResolvedAliasCount de sessiegrootte tonen

IXLSReportDataView.TryGetValue zoekt één benoemde waarde op zonder een exception te geven, als aanvulling op de geïndexeerde accessors Count, Namesen Values accessors

Relaties en luie tabelcombinators

TXLSReportRowIndexes en TXLSReportRelationIndex bewaren kindrijnummers in buckets met samengestelde sleutels; gebruik FindChildRows of CreateChildCursor en inspecteer BucketCount of IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregateen TXLSReportJoinKind configureren TXLSReportTableFactory, whose row filters compare through TXLSReportFilterOperator (xrfoEqual, xrfoNotEqual, xrfoGreater, xrfoGreaterEqual, xrfoLess, xrfoLessEqual, xrfoContains, xrfoStartsWith, xrfoEndsWith)

Benoemde en expliciete bereikbanden

TXLSReportBandKind selecteert rij-, kolom- of kruistabelexpansie, en TXLSReportBandState rapporteert de levenscyclusstatus

TXLSCompiledReportBand accepteert een gedefinieerde naam met exact bereik of CreateForRangeen breidt daarna uit via de Run -overloads; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCounten State stellen het gecompileerde plan bloot

EmptyBandPolicy (type TXLSEmptyBandPolicy) stuurt wat de band met zijn templaterijen doet wanneer de dataset leeg is — xreKeepTemplate laat de rijen onaangetast, xreClearTemplate wist de bandcellen inclusief plaatshouders en xreDeleteTemplate verwijdert de templaterijen — en DeleteLastRow verwijdert de laatste BandHeight rijen van het uitgebreide blok nadat zijn kopieën zijn geland, zodat afsluitende X-range-scheidingsrijen samenvallen

FixedBand laat rijbands de rijen onder de template overschrijven in plaats van nieuwe in te voegen, waardoor omliggende inhoud op een vaste positie blijft

Rij- en kolombereikbanden klonen threaded opmerkinggesprekken wanneer elke root en elk antwoord binnen het templaterangebied valt; tekst- en weergavenaam-placeholders worden per record geëvalueerd, gekopieerde opmerkingen krijgen nieuwe ID's en opnieuw gemapte bovenliggende ID's, en bestaande persoonsrecords van de werkmap worden hergebruikt

Compilatie wijst gesprekken af die over de templategrens zijn gesplitst, ontbrekende bovenliggende items, dubbele ID's en ongeldige celankers vóór expansie; ankeroverloop wordt gecontroleerd vóór werkbladmutatie, en een mislukte of geannuleerde run ruimt gegenereerde gesprekken op terwijl de templatestaat wordt hersteld

TXLSCompiledTableReportBand.Run breidt één gegevenstemplatesjabloonrij van een Excel-tabel uit met behoud van de tabelmetagegevens; inspecteer TableName, Sheet, SheetIndex, ExcelTable, TemplateRowen State, en stel dezelfde V2-beeldeigenschappen in die bereikbanden beschikbaar stellen

Range- en Excel-tabelbands delen ErrorMode, StrictDataAccess, RuntimeLimitsen immutabele LastResult -momentopnamen; xremWriteAndContinue schrijft alleen expliciete herstelbare celfouten als letterlijke diagnostiek, registreert de bron BandInputRow en de werkelijke uitvoercoördinaten en zet latere doelen en rijen voort, terwijl structurele, annulerings-, resourcegrens-, callback- en rollbackfouten fataal blijven

TXLSCompiledSheetReportBand.Run maakt werkbladen per record met NameColumn, NamePrefixen DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run maakt vervolgwerkbladen met NamePrefix en DeleteTemplateAfterRun

Sjablonen voor volledige werkmappen

TXLSReportTemplateTarget en TXLSReportTemplateTargets selecteren cellen, opmerkingen, hyperlinks, vormen, kop- en voetteksten, werkbladnamen, gedefinieerde namen en documenteigenschappen

TXLSCompiledReportTemplate.Compile legt doelen en expressies vast, Analyze retourneert geadresseerde TXLSReportIssues, de Run -overloads passen waarden toe en WriteDiagnostics schrijft problemen naar een werkblad; TargetAreas, TargetCounten UserTableCount beschrijven het gecompileerde oppervlak en de geregistreerde gebruikerstabellen

ProcessStructuralDirectives (standaard True) laat een template- Run de structurele directives {{#delete}} en {{#format}} uitvoeren nadat de waardedoelen zijn toegepast — de TXLSReportDirectiveProcessor erachter parseert de bereiken, past ze toe en rapporteert via AppliedCount hoeveel hij heeft afgehandeld — en CreateEncrypted opent een versleutelde template met zijn wachtwoord en compileert die, terwijl de werkmap bereikbaar blijft via de property Workbook property

TXLSReportIssueKind, TXLSReportIssueen TXLSReportIssues identificeren misvormde, ontbrekende, ongeldige, onbekende of cyclische plaatshouderinhoud met doel- en celcoördinaten

Includes, afbeeldingen en opmaak

IXLSReportIncludeResolver.Resolve levert benoemde fragmenten en de vlag Immutable maakt veilig hergebruik mogelijk; TXLSReportIncludeLibrary biedt Add, Remove, Clear, Freeze, Resolve, Counten Immutable

IXLSReportImageProvider.TryGetImage retourneert een TXLSReportImageValue die door TXLSReportImageFitwordt geconfigureerd; TXLSReportMissingImagePolicy beheert ontbrekende bronnen, terwijl TXLSReportImageBinder.Apply, ApplyTarget, MissingPolicy, and ClearDirectiveCell update exact image directives

TXLSReportImageBinder.ApplyTargetV2 verbindt één directivecel via het V2-providercontract en stuurt een TXLSReportTransformImageEvent door die de opgeloste payload kan herschrijven voordat deze op zijn plek landt; de opgeloste placeholder zelf is een TXLSReportEvaluatedTarget whose TXLSReportEvaluatedTargetKind distinguishes xretNone, xretText, xretValue, and xretFormula; IXLSReportImageCancellation.IsCancellationRequested laat langlopende providers een coöperatieve annulering opmerken

IXLSReportImageDataProviderV2.GetImage receives TXLSReportImageRequest met stabiele werkbladidentiteit, gecompileerd doel, band- en tabelnamen, logische rijen en cursorrijen, een alleen-lezen weergave van de huidige rij, directive- en anchorcellen, doeldimensies en -offsets in EMU, en IXLSReportImageCancellation

TXLSReportImageResult carries a TXLSReportImagePayload whose Kind (TXLSReportImagePayloadKind) selects xripMissing, bytes of een stream, waarbij de levensduur van de stream wordt aangegeven door TXLSReportImageStreamOwnership: xrisoBorrowed streams blijven eigendom van de aanroeper en herstellen hun positie wanneer ze seekbaar zijn, terwijl xrisoTransferred streams worden precies één keer vrijgegeven; optionele SourceWidth, SourceHeight, SourceDpiX, and SourceDpiY legt de fysieke geometrie van de bron vast of overschrijft die

xrifNatural uses the source physical size, xrifContain schaalt en centreert binnen de doelbox, xrifCover vult de box met symmetrische bijsnijding van de bron, en xrifStretch vult hem zonder de beeldverhouding te bewaren; de geometrie van PNG, JPEG, GIF, BMP, EMF en WMF wordt uit begrensde headers gelezen zonder pixels te decoderen

OnTransformImage draait nadat providergegevens zijn gesnapshotst en vóór het muteren van het werkblad; MaximumImageBytes staat standaard op 64 MiB en payload-handtekeningen, geometry-headers, dimensie- en DPI-paren, rasterzijde en pixellimieten, anchors en rastercoördinaten worden gevalideerd vóór de binding

TXLSXImage.OffsetXEMU en OffsetYEMU exacte afbeeldingsdirectieven bijwerken

TXLSReportDynamicFormat en TXLSReportFormatEvent laten een uitvoerder getalnotaties, rijhoogtes en kolombreedtes per doel toepassen

Herbruikbare uitvoering

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgressen TXLSReportRunProgressEvent beschrijven voortgangs- en annuleringsgrenzen

TXLSCompiledReportRunner stelt Run, RunToStream, RunToFile, RunToEncryptedFileen Cancelbloot, met ReportTemplate, State, Progress, OnProgressen OnFormat die herbruikbare uitvoering sturen; mislukte validatie veroorzaakt EXLSReportData vóór deterministische schrijfacties

ErrorMode (type TXLSReportErrorMode) staat standaard op xremStop; xremWriteAndContinue behandelt alleen expliciete EXLSReportRecoverableData -fouten en resolverresultaten DataError , legt geordende immutabele problemen vast in LastResult (een IXLSReportRunResult met State, AppliedCount, IssueCount, geïndexeerde Issuesen de FailureClassName / FailureMessage van een fatale fout), waarvan de TXLSReportRuntimeIssue -momentopnamen hun Category tonen (een TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProviderof xrricExpression) en TargetIndex, SheetName, Colen of het probleem al WasWritten in de uitvoer was gemeld, en eindigt als xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults staat 100.000 bewaarde problemen toe, 512 tekens per gesaniteerde melding en 16 MiB aan probleemgeheugen; wijs een positief eigen RuntimeLimits -record toe vóór een run en laat RuntimeDiagnosticsSheetName leeg, tenzij één gestructureerd diagnostiekwerkblad nodig is

Herstelbare celwaarden en formules worden letterlijke tekst [Report error CODE] message , veilige niet-celdoelen behouden hun oorspronkelijke waarde, en een optioneel diagnostiekwerkblad markeert die gestructureerde problemen als geschreven; fouten in werkbladnamen en formules van gedefinieerde namen stoppen altijd, omdat ze de werkmapstructuur kunnen veranderen

Door de resolver gemelde gegevensfouten, deling door nul in expressies en ongeldige reguliere expressies gebruiken stabiele provider- of expressiecategorieën; gegoode resolverexceptions en alle callback-, annulerings-, resourcegrens-, rollback-, serialisatie-, beveiligings- en structurele fouten blijven fataal

RunToStream, RunToFileen RunToEncryptedFile stagen serialisatie binnen dezelfde run- en datasessie-levensduur en publiceren één keer; elke fatale, geannuleerde, serialisatie-, partiele streamschrijf- of doelvervangingsfout behoudt de volledige vorige bestemming en geeft tijdelijke opslag vrij vóór de terugkeer

Een niet-lege uitvoerstream moet leesbaar, beschrijfbaar, schaalbaar en doorzoekbaar zijn zodat rollback de oorspronkelijke bytes, grootte en positie kan herstellen; momentopnamen tot 8 MiB blijven in het geheugen en grotere gebruiken beheerde tijdelijke opslag, terwijl een geslaagde commit de stream op positie nul achterlaat

Onversleutelde uitvoer gebruikt het bronformaat van de gegenereerde werkmap, dus een ODS-template produceert een ODS-stream of -bestand met de vereiste package-metadata; versleutelde uitvoer gebruikt blijft de versleutelde Office-container

ImageProvider behoudt het oorspronkelijke compatibiliteitscontract; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicyen ClearImageDirectiveCell laten een runner, generator, range band of Excel-tabelband voorgecompileerde {{#image Key}} -doelen direct consumeren; beide providers weglaten laat die directivecellen ongewijzigd

AutofitMode (type TXLSReportAutofitMode) kiest een autofit voor het hele blad (xramNone, xramRows, xramColumnsof xramBoth), toegepast één keer nadat alle doelen hebben gedraaid, en AutofitAdjustment is een extra margefactor (1.0 = geen, 1.1 = 10% hogere rijen)

Generatielevenscyclus en templatebronnen

TXLSReportLifecyclePhase identificeert de grenzen van template-lezing, werkmapgeneratie en werkbladgeneratie, terwijl TXLSReportLifecycleOutcome entered-, completed-, canceled- en failed-callbacks onderscheidt

TXLSReportLifecycleContext levert de actieve werkmap en het actieve werkblad, stabiele werkbladidentiteit, oorspronkelijke en huidige coördinaten, een read-only IXLSReportDataView, het aantal doelen en details van de eerste fout; elke entered before-event krijgt een gekoppeld after-event, ook wanneer de generatie wordt geannuleerd of mislukt

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheeten AfterGenerateSheet observeren een bevroren set oorspronkelijke werkbladen; structurele wijzigingen uit callbacks triggeren een compilatieverversing zonder nieuw aangemaakte werkbladen aan de huidige run toe te voegen

TXLSReportGenerator accepteert een werkmap, bestandsnaam, stream in beheer van de aanroeper of versleuteld bestand en voegt BeforeReadTemplate plus AfterReadTemplate toe aan de generatie-events; TXLSReportModificationMode kiest compatibele in-place mutatie of geïsoleerde generatie via atomische kloon. Read-only SourceKind (type TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStreamof xrtsEncryptedFile) en TemplateWorkbook rapporteren de geconfigureerde templatebron, terwijl ModificationMode en IncludeResolver vóór een run instelbaar zijn

Bestands- en streamtemplates staan standaard op xrmAtomicClone; doorzoekbare invoerstreams herstellen hun oorspronkelijke positie, forward-only streams worden in begrensde blokken geconsumeerd, streams van de aanroeper blijven open en uitvoerstreams of -bestanden worden pas vervangen na geslaagde voltooiing

Planning, controle en migratie

TXLSReportPaginationPlanner biedt de plannen KeepTogether, SplitRows, MergeSimilaren BalanceColumns voor vaste voetteksten en gebalanceerde uitvoer

TXLSReportTemplateChecker biedt Check, CheckBanden CheckTableBand; TXLSReportTemplateMigrator biedt MigrateText en MigrateWorkbook voor ondersteunde verouderde plaatshoudervormen

Voorbeeld

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

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;

De Delphi-voorbeelden FeatureShowcase en C++Builder XlsxFeatureGallery bevatten volledig uitvoerbare versies die de status completed-with-errors en het aantal problemen verifiëren voordat de runner wordt vrijgegeven

Zie ook

• Geavanceerde werkmapworkflows
• TXLSXWorkbook
• TXLSPaginationModel