Kompileret rapporterings-API

Enheden lxReport kompilerer pladsholdere og strukturelle rapportbånd én gang og anvender derefter caller-ejede data gennem afgrænsede cursors uden at genskanne de genererede projektmappe-objekter

Tabel- og cursorkontrakter

Kontrollerede forespørgselsudbydere

IXLSReportQueryExecutor.ExecuteReadOnly holder forespørgselsudførelsen hos værten og accepterer kun definitioner, der er registreret af programkoden

TXLSReportQueryParameter, TXLSReportQueryParametersog TXLSReportQueryDefinition viser Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameterog ClearParameters

TXLSReportQueryProvider bruger RegisterQuery, RemoveQuery, Clearog TryGetTable, hvor Count, Definitionsog MaximumTimeoutMS viser hvidlisten og timeout-loftet

Datasessioner pr. kørsel

IXLSReportDataSession er den isolerede lazy-cache bag én rapportkørsel: DeclareRequest registrerer en TXLSReportDataRequest (type TXLSReportDataRequestKind: xrdrkNamed eller xrdrkUser), hvis TXLSReportDataSource (type TXLSReportDataSourceKind: uspecificeret, celle, intervalbånd, tabelbånd eller udtryk) og TXLSReportDataParameter -liste beskriver kilden og dens værdier, og hvis RunControl er værtens IXLSReportRunControl -annullerings-handle; HasResolver tester en providernøgle, TryGetTable og RequireTable læser cachede aliasser, TryResolveTable og RequireResolvedTable opløser on demand til en TXLSReportDataResolveResult (status TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFoundeller xrdrsDataError), og TryGetState rapporterer en TXLSReportDataSessionState af loading, resolved, not found eller data error, mens CachedAliasCount og ResolvedAliasCount eksponerer sessionens størrelse

IXLSReportDataView.TryGetValue slår én navngiven værdi op uden at raise og supplerer de indekserede accessors Count, Namesog Values accessors

Relationer og lazy-tabelkombinatorer

TXLSReportRowIndexes og TXLSReportRelationIndex gemmer underordnede rækkenumre i buckets med sammensatte nøgler; brug FindChildRows eller CreateChildCursor , og inspicér BucketCount eller IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregateog TXLSReportJoinKind konfigurerer TXLSReportTableFactory, hvis rækkefiltre sammenligner via TXLSReportFilterOperator (xrfoEqual, xrfoNotEqual, xrfoGreater, xrfoGreaterEqual, xrfoLess, xrfoLessEqual, xrfoContains, xrfoStartsWith, xrfoEndsWith)

Navngivne og eksplicitte intervalbånd

TXLSReportBandKind vælger række-, kolonne- eller crosstab-udfoldning, og TXLSReportBandState rapporterer livscyklustilstandene klar, kører, fuldført, fuldført med fejl, annulleret eller fejlet

TXLSCompiledReportBand accepterer et defineret navn med præcis rækkevidde eller CreateForRangeog udvider derefter gennem Run -overloads; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCountog State viser den kompilerede plan

EmptyBandPolicy (type TXLSEmptyBandPolicy) styrer, hvad båndet gør ved sine skabelonrækker, når datasættet er tomt — xreKeepTemplate lader rækkerne stå urørte, xreClearTemplate rydder båndcellerne inklusive pladsholdere, og xreDeleteTemplate sletter skabelonrækkerne — og DeleteLastRow fjerner de sidste BandHeight rækker af den udvidede blok, efter dens kopier er landet, så efterstillede X-interval-separatorrækker kollapser

FixedBand får rækkebånd til at overskrive rækkerne under skabelonen i stedet for at indsætte nye, så det omkringliggende indhold beholder sin faste position

Række- og kolonneintervalbånd kloner trådede kommentarsamtaler, når hver rod og hvert svar hører til skabelonområdet; tekst- og visningsnavne-pladsholdere evalueres for hver post, kopierede kommentarer får nye identifikatorer og remappede overordnede identifikatorer, og eksisterende personrecords i projektmappen genbruges

Kompileringen afviser samtaler, der er splittet over skabelongrænsen, manglende forældre, dubletidentifikatorer og ugyldige celleankre, før udvidelsen; ankeroverflow tjekkes, før regnearket muteres, og en fejlet eller annulleret kørsel fjerner genererede samtaler, mens skabelontilstanden gendannes

TXLSCompiledTableReportBand.Run udvider én data-skabelonrække i en Excel-tabel, samtidig med at tabelmetadata bevares; inspicér TableName, Sheet, SheetIndex, ExcelTable, TemplateRowog State, og konfigurer de samme V2-billedegenskaber, som intervalbåndene eksponerer

Interval- og Excel-tabelbånd deler ErrorMode, StrictDataAccess, RuntimeLimitsog uforanderlige LastResult -snapshots; xremWriteAndContinue skriver kun eksplicitte, gendannelige cellefejl som literale diagnostikker, registrerer kildens BandInputRow og de faktiske outputkoordinater og fortsætter med senere mål og rækker, mens strukturelle, annullerings-, ressourcegrænse-, callback- og rollback-fejl forbliver fatale

TXLSCompiledSheetReportBand.Run opretter ark pr. post ved hjælp af NameColumn, NamePrefixog DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run opretter fortsættelsesark ved hjælp af NamePrefix og DeleteTemplateAfterRun

Hele-arbejdsbog-skabeloner

TXLSReportTemplateTarget og TXLSReportTemplateTargets vælger celler, kommentarer, hyperlinks, figurer, sidehoveder og sidefødder, arkenavne, definerede navne og dokumentegenskaber

TXLSCompiledReportTemplate.Compile fanger mål og udtryk, Analyze returnerer adresserede TXLSReportIssues, Run-overloadene anvender værdierne, og Run skriver problemerne til et regneark; WriteDiagnostics , TargetAreasog TargetCountbeskriver den kompilerede overflade og de registrerede brugertabeller UserTableCount beskriver den kompilerede overflade og de registrerede brugertabeller

ProcessStructuralDirectives (standard True) får en skabelons Run til at udføre de strukturelle direktiver {{#delete}} og {{#format}} , efter værdimålene er anvendt — TXLSReportDirectiveProcessor bagved parser områderne, anvender dem og rapporterer via AppliedCount , hvor mange den har håndteret — og CreateEncrypted åbner en krypteret skabelon med dens adgangskode og kompilerer den, mens projektmappen forbliver tilgængelig via egenskaben Workbook property

TXLSReportIssueKind, TXLSReportIssueog TXLSReportIssues identificerer fejlbehæftet, manglende, ugyldigt, ukendt eller cyklisk pladsholderindhold med mål- og cellekoordinater

Inkluderinger, billeder og formatering

IXLSReportIncludeResolver.Resolve leverer navngivne fragmenter, og dets Immutable -flag tillader sikker genbrug; TXLSReportIncludeLibrary leverer Add, Remove, Clear, Freeze, Resolve, Countog Immutable

IXLSReportImageProvider.TryGetImage returnerer en TXLSReportImageValue konfigureret af TXLSReportImageFit; TXLSReportMissingImagePolicy styrer manglende ressourcer, mens TXLSReportImageBinder.Apply, ApplyTarget, MissingPolicyog ClearDirectiveCell opdaterer præcise billeddirektiver

TXLSReportImageBinder.ApplyTargetV2 binder én direktivcelle via V2-provider-kontrakten og videresender en TXLSReportTransformImageEvent , der kan omskrive det opløste payload, før det lander; selve den opløste pladsholder er en TXLSReportEvaluatedTarget , hvis TXLSReportEvaluatedTargetKind adskiller xretNone, xretText, xretValueog xretFormula; IXLSReportImageCancellation.IsCancellationRequested lader langvarige providere observere et kooperativt annulleringssignal

IXLSReportImageDataProviderV2.GetImage modtager en TXLSReportImageRequest med stabil regnearksidentitet, kompileret mål, bånd- og tabelnavne, logiske og cursor-rækker, en skrivebeskyttet visning af den aktuelle række, direktiv- og anker celler, måldimensioner og forskydninger i EMU samt IXLSReportImageCancellation

TXLSReportImageResult bærer et TXLSReportImagePayload , hvis Kind (TXLSReportImagePayloadKind) vælger xripMissing, bytes eller en stream, med streamens levetid deklareret af TXLSReportImageStreamOwnership: xrisoBorrowed -streams forbliver ejet af kalderen og gendanner deres position, når de er seekable, mens xrisoTransferred -streams frigøres præcis én gang; valgfrie SourceWidth, SourceHeight, SourceDpiXog SourceDpiY bekræfter eller overskriver den fysiske kildegeometri

xrifNatural bruger kildens fysiske størrelse, xrifContain skalerer og centrerer inden for målboksen, xrifCover fylder boksen med symmetrisk beskæring af kilden, og xrifStretch fylder den uden at bevare billedforholdet; geometrien for PNG, JPEG, GIF, BMP, EMF og WMF læses fra afgrænsede headers uden at dekode pixels

OnTransformImage kører, efter der er taget snapshot af providerdataene, og før regnearket muteres; MaximumImageBytes er som standard 64 MiB, og payload-signaturer, geometriheaders, dimension- og DPI-par, raster-side- og pixelgrænser, ankre og gitterkoordinater valideres, før bindingen sker

TXLSXImage.OffsetXEMU og OffsetYEMU bevarer et billedes position inde i sin celle eller sit absolutte anker på tværs af XLSX- og ODS-roundtrips

TXLSReportDynamicFormat og TXLSReportFormatEvent lader en runner anvende talformater, rækkehøjder og kolonnebredder pr. mål

Genanvendelig udførelse

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgressog TXLSReportRunProgressEvent beskriver fremskridt og annulleringsgrænser

TXLSCompiledReportRunner eksponerer Run, RunToStream, RunToFile, RunToEncryptedFileog Cancelmed ReportTemplate, State, Progress, OnProgressog OnFormat til at styre den genanvendelige udførelse; fejlet validering udløser EXLSReportData , før der skrives deterministisk

ErrorMode (type TXLSReportErrorMode) er som standard xremStop; xremWriteAndContinue håndterer kun eksplicitte EXLSReportRecoverableData -fejl og resolverens DataError -resultater, registrerer ordnede, uforanderlige problemer i LastResult (en IXLSReportRunResult med State, AppliedCount, IssueCount, indekserede Issuessamt FailureClassName / FailureMessage for en fatal fejl), hvis TXLSReportRuntimeIssue -snapshots eksponerer deres Category (en TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProvidereller xrricExpression) og rapporterer TargetIndex, SheetName, Colog om problemet allerede var WasWritten ind i outputtet, og afslutter som xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults tillader 100.000 gemte problemer, 512 tegn pr. saneret besked og 16 MiB problemlager; tildel en positiv, tilpasset RuntimeLimits -post før en kørsel, og lad RuntimeDiagnosticsSheetName stå tom, medmindre der skal ét struktureret diagnostikregneark

Gendannelige celleværdier og formler bliver til literal [Report error CODE] message -tekst, sikre ikke-celle-mål bevarer deres oprindelige værdi, og et valgfrit diagnostikregneark markerer de strukturerede problemer som skrevne; fejl med arkenavne og formler for definerede navne stopper altid, fordi de kan ændre projektbogens struktur

Resolver-deklarerede datafejl, divisionsudtryk med nul i udtryk og ugyldige regulære udtryk bruger stabile provider- eller udtrykskategorier; kastede resolver-undtagelser og alle callback-, annullerings-, ressourcegrænse-, rollback-, serialiserings-, sikkerheds- og strukturelle fejl forbliver fatale

RunToStream, RunToFileog RunToEncryptedFile stage'er serialiseringen inden for samme kørsels- og datasessionslevetid og publicerer derefter én gang; enhver fatal, annulleret, serialiserings-, delvis stream-skrive- eller destinationserstatningsfejl bevarer den komplette tidligere destination og frigør det midlertidige lager, før der returneres

En ikke-tom output-stream skal kunne læses, skrives, størrelsesændres og seekes, så rollback kan gendanne dens oprindelige bytes, størrelse og position; snapshots op til 8 MiB forbliver i hukommelsen, og større snapshots bruger styret midlertidigt lager, mens en vellykket commit efterlader streamen positioneret ved nul

Ukrypteret output bruger den genererede projektbogs kildeformat, så en ODS-skabelon giver en ODS-stream eller -fil med dens krævede pakkemetadata; krypteret output fortsætter med at bruge den krypterede Office-beholder

ImageProvider bevarer den oprindelige kompatibilitetskontrakt; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicyog ClearImageDirectiveCell lader en runner, generator, intervalbånd eller Excel-tabelbånd forbruge prækompilerede {{#image Key}} -mål direkte; udelades begge providere, forbliver disse direktivceller uændrede

AutofitMode (type TXLSReportAutofitMode) vælger autofit for hele arket (xramNone, xramRows, xramColumnseller xramBoth), anvendt én gang, efter alle mål er kørt, og AutofitAdjustment er en ekstra headroom-faktor (1.0 = ingen, 1.1 = 10 % højere rækker)

Generationslivscyklus og skabelonkilder

TXLSReportLifecyclePhase identificerer grænserne for skabelonlæsning, projektmappengenerering og regnearksgenerering, mens TXLSReportLifecycleOutcome adskiller entered-, completed-, canceled- og failed-callbacks

TXLSReportLifecycleContext leverer den aktive projektmappe og regneark, stabil regnearksidentitet, originale og aktuelle koordinater, en skrivebeskyttet IXLSReportDataView, antal mål og detaljer om den første fejl; hver entered before-event får et parret after-event, selv når genereringen annulleres eller fejler

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheetog AfterGenerateSheet observerer et frossen sæt af originale regneark; callback-drevne strukturendringer udløser en opfriskning af kompileringen uden at tilføje nyoprettede ark til den aktuelle kørsel

TXLSReportGenerator accepterer en projektmappe, et filnavn, en caller-ejet stream eller en krypteret fil og tilføjer BeforeReadTemplate samt AfterReadTemplate til genereringshændelserne; TXLSReportModificationMode vælger kompatibel in-place-mutation eller isoleret generering via atomklon. Skrivebeskyttet SourceKind (type TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStreameller xrtsEncryptedFile) og TemplateWorkbook rapporterer den konfigurerede skabelonkilde, mens ModificationMode og IncludeResolver kan sættes før en kørsel

Fil- og streamskabeloner er som standard xrmAtomicClone; seekable inputstreams gendanner deres oprindelige position, forward-only-streams forbruges i afgrænsede blokke, caller-streams forbliver åbne, og output-streams eller -filer erstattes først efter vellykket fuldførelse

Planlægning, kontrol og migrering

TXLSReportPaginationPlanner leverer KeepTogether-, SplitRows-, MergeSimilar- og BalanceColumns -planer for faste sidefødder og afbalanceret output

TXLSReportTemplateChecker leverer Check, CheckBandog CheckTableBand; TXLSReportTemplateMigrator leverer MigrateText og MigrateWorkbook til understøttede ældre pladsholderformer

Eksempel

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

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's FeatureShowcase og C++Builder's XlsxFeatureGallery indeholder komplette, kørbare versioner, der verificerer completed-with-errors-tilstanden og antallet af problemer, før runneren frigives

Se også

• Avancerede arbejdsbogs-arbejdsgange
• TXLSXWorkbook
• TXLSPaginationModel