API för kompilerad rapportering

Enheten lxReport kompilerar platshållare och strukturella rapportband en gång och tillämpar sedan ägardata genom begränsade markörer utan att skanna om genererade arbetsboksobjekt

Kontrakt för tabeller och markörer

Kontrollerade frågeleverantörer

IXLSReportQueryExecutor.ExecuteReadOnly håller frågekörningen värdägd och accepterar endast definitioner som registrerats av applikationskoden

TXLSReportQueryParameter, TXLSReportQueryParametersoch TXLSReportQueryDefinition exponerar Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameteroch ClearParameters

TXLSReportQueryProvider använder RegisterQuery, RemoveQuery, Clearoch TryGetTable, där Count, Definitionsoch MaximumTimeoutMS exponerar vitlistan och timeout-taket

Datasessioner per körning

IXLSReportDataSession är den isolerade lazycachen bakom en rapportkörning: DeclareRequest registrerar en TXLSReportDataRequest (typ TXLSReportDataRequestKind: xrdrkNamed eller xrdrkUser) vars TXLSReportDataSource (typ TXLSReportDataSourceKind: ospecificerad, cell, intervallband, tabellband eller uttryck) och TXLSReportDataParameter -lista beskriver källan och dess värden, och vars RunControl är värdens IXLSReportRunControl -avbrytninghandtag; HasResolver testar en leverantörsnyckel, TryGetTable och RequireTable läser cachade alias, TryResolveTable och RequireResolvedTable löser på begäran till ett TXLSReportDataResolveResult (status TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFoundeller xrdrsDataError), och TryGetState rapporterar en TXLSReportDataSessionState av loading, resolved, not found eller data error, medan CachedAliasCount och ResolvedAliasCount exponerar sessionsstorleken

IXLSReportDataView.TryGetValue slår upp ett namngivet värde utan att kasta undantag och kompletterar de indexerade åtkomsterna Count, Namesoch Values accessors

Relationer och lata tabellkombinatorer

TXLSReportRowIndexes och TXLSReportRelationIndex behåller radnummer för underordnade rader i hinkar med sammansatta nycklar; använd FindChildRows eller CreateChildCursor och inspektera BucketCount eller IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregateoch TXLSReportJoinKind konfigurerar TXLSReportTableFactory, vars radfilter jämför via TXLSReportFilterOperator (xrfoEqual, xrfoNotEqual, xrfoGreater, xrfoGreaterEqual, xrfoLess, xrfoLessEqual, xrfoContains, xrfoStartsWith, xrfoEndsWith)

Namngivna och explicita intervallband

TXLSReportBandKind väljer rad-, kolumn- eller korsfliksutbyggnad, och TXLSReportBandState rapporterar livscykeltillstånden ready, running, completed, completed-with-errors, canceled eller failed

TXLSCompiledReportBand accepterar ett definierat namn med exakt omfattning eller CreateForRangeoch expanderar sedan genom Run -överlagringarna; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCountoch State exponerar den kompilerade planen

EmptyBandPolicy (typ TXLSEmptyBandPolicy) styr vad bandet gör med sina mallrader när datauppsättningen är tom — xreKeepTemplate lämnar raderna orörda, xreClearTemplate rensar bandcellerna inklusive platshållare, och xreDeleteTemplate tar bort mallraderna — och DeleteLastRow tar bort de sista BandHeight raderna av det expanderade blocket efter att dess kopior landat, så att avslutande X-områdesavgränsarrader kollapsar

FixedBand låter radband skriva över raderna under mallen i stället för att infoga nya, vilket håller omgivande innehåll på en fast position

Rad- och kolumnområdeband klonar trådade kommentarkonversationer när varje rot och varje svar tillhör mallområdet; text- och visningsnamnsplatshållare utvärderas per post, kopierade kommentarer får nya identifierare och omkartlagda överordnade identifierare, och befintliga personposter i arbetsboken återanvänds

Kompileringen avvisar konversationer som delas över mallgränsen, saknade överordnade, dubblettidentifierare och ogiltiga cellankare innan expansionen; ankarets överlopp kontrolleras innan kalkylbladet muteras, och en misslyckad eller avbruten körning tar bort genererade konversationer medan malltillståndet återställs

TXLSCompiledTableReportBand.Run expanderar en Excel-tabells datamallrad samtidigt som tabellmetadata bevaras; inspektera TableName, Sheet, SheetIndex, ExcelTable, TemplateRowoch State, och konfigurera samma V2-bildegenskaper som intervallbanden exponerar

Intervall- och Excel-tabellband delar ErrorMode, StrictDataAccess, RuntimeLimitsoch oföränderliga LastResult -ögonblicksbilder; xremWriteAndContinue skriver bara explicita återhämtningsbara cellfel som literal diagnostik, registrerar källans BandInputRow och faktiska utkoordinater, och fortsätter med senare mål och rader, medan strukturella, avbrotts-, resursgräns-, callback- och återställningsfel förblir fatala

TXLSCompiledSheetReportBand.Run skapar blad per post med hjälp av NameColumn, NamePrefixoch DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run skapar fortsättningsblad med hjälp av NamePrefix och DeleteTemplateAfterRun

Hela arbetsboksmallar

TXLSReportTemplateTarget och TXLSReportTemplateTargets väljer celler, kommentarer, hyperlänkar, former, sidhuvuden och sidfötter, bladnamn, definierade namn och dokumentegenskaper

TXLSCompiledReportTemplate.Compile fångar mål och uttryck, Analyze returnerar adresserade TXLSReportIssues, Run -överlagringarna tillämpar värden och WriteDiagnostics skriver problem till ett arbetsblad; TargetAreas, TargetCountoch UserTableCount beskriver den kompilerade ytan och de registrerade användartabellerna

ProcessStructuralDirectives (standard True) gör att en mall- Run kör de strukturella direktiven {{#delete}} och {{#format}} efter att värdmålen tillämpats — TXLSReportDirectiveProcessor bakom den tolkar områdena, tillämpar dem och rapporterar hur många den hanterade via AppliedCount — och CreateEncrypted öppnar en krypterad mall med sitt lösenord och kompilerar den samtidigt som arbetsboken hålls nåbar via egenskapen Workbook property

TXLSReportIssueKind, TXLSReportIssueoch TXLSReportIssues identifierar felformaterat, saknat, ogiltigt, okänt eller cykliskt platshållarinnehåll med mål- och cellkoordinater

Inkluderingar, bilder och formatering

IXLSReportIncludeResolver.Resolve levererar namngivna fragment och dess Immutable -flagga tillåter säker återanvändning; TXLSReportIncludeLibrary tillhandahåller Add, Remove, Clear, Freeze, Resolve, Countoch Immutable

IXLSReportImageProvider.TryGetImage returnerar ett TXLSReportImageValue som konfigureras av TXLSReportImageFit; TXLSReportMissingImagePolicy styr saknade resurser, medan TXLSReportImageBinder.Apply, ApplyTarget, MissingPolicyoch ClearDirectiveCell uppdaterar exakta bilddirektiv

TXLSReportImageBinder.ApplyTargetV2 binder en direktivcell genom V2-leverantörskontraktet och vidarebefordrar en TXLSReportTransformImageEvent som kan skriva om den lösta nyttolasten innan den landar; själva den lösta platshållaren är en TXLSReportEvaluatedTarget vars TXLSReportEvaluatedTargetKind skiljer mellan xretNone, xretText, xretValueoch xretFormula; IXLSReportImageCancellation.IsCancellationRequested låter långvariga leverantörer iaktta en kooperativ avbrytning

IXLSReportImageDataProviderV2.GetImage tar emot en TXLSReportImageRequest med stabil kalkylbladsidentitet, kompilerat mål, band- och tabellnamn, logiska rader och markörrader, en skrivskyddad vy av aktuell rad, direktiv- och ankarceller, måldimensioner och offset i EMU samt IXLSReportImageCancellation

TXLSReportImageResult bär en TXLSReportImagePayload vars Kind (TXLSReportImagePayloadKind) väljer xripMissing, byte eller en ström, med strömmens livstid deklarerad av TXLSReportImageStreamOwnership: xrisoBorrowed -strömmar förblir anropsägda och återställer sin position när de är sökbara, medan xrisoTransferred -strömmar släpps exakt en gång; valfria SourceWidth, SourceHeight, SourceDpiXoch SourceDpiY bekräftar eller åsidosätter fysisk källgeometri

xrifNatural använder källans fysiska storlek, xrifContain skalar och centrerar inom målramen, xrifCover fyller ramen med symmetrisk beskärning av källan, och xrifStretch fyller den utan att bevara bildförhållandet; geometrin för PNG, JPEG, GIF, BMP, EMF och WMF läses från avgränsade huvuden utan pixeldekodning

OnTransformImage körs efter att leverantörsdata ögonblicksbildats och före mutering av arbetsbladet; MaximumImageBytes är som standard 64 MiB och nyttolastsignaturer, geometrihuvuden, dimension- och DPI-par, rasterkanter och pixelgränser, ankare och rutnätskoordinater valideras innan bindning

TXLSXImage.OffsetXEMU och OffsetYEMU bevarar en bilds position inuti sin cell eller absoluta ankare genom XLSX- och ODS-roundtrips

TXLSReportDynamicFormat och TXLSReportFormatEvent låter en körare tillämpa talformat, radhöjder och kolumnbredder per mål

Återanvändbar körning

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgressoch TXLSReportRunProgressEvent beskriver förlopps- och avbrytningsgränser

TXLSCompiledReportRunner exponerar Run, RunToStream, RunToFile, RunToEncryptedFileoch Cancel, där ReportTemplate, State, Progress, OnProgressoch OnFormat styr återanvändbar körning; misslyckad validering utlöser EXLSReportData före deterministiska skrivningar

ErrorMode (typ TXLSReportErrorMode) är som standard xremStop; xremWriteAndContinue hanterar bara explicita EXLSReportRecoverableData -fel och resolvers DataError -resultat, registrerar ordnade oföränderliga problem i LastResult (ett IXLSReportRunResult som exponerar State, AppliedCount, IssueCount, indexerade Issuessamt FailureClassName / FailureMessage för ett fatalistiskt fel) vars TXLSReportRuntimeIssue -ögonblicksbilder exponerar sin Category (en TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProvidereller xrricExpression) och rapporterar TargetIndex, SheetName, Coloch huruvida problemet redan WasWritten till utdata, och avslutar som xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults tillåter 100 000 kvarhållna problem, 512 tecken per sanerat meddelande och 16 MiB problemminne; tilldela en positiv egen RuntimeLimits -post före en körning, och låt RuntimeDiagnosticsSheetName vara tom om inte ett strukturerat diagnostikblad krävs

Återhämtningsbara cellvärden och formler blir literal text [Report error CODE] message , säkra icke-cellmål behåller sitt ursprungliga värde, och ett valfritt diagnostikblad markerar de strukturerade problemen som skrivna; fel på kalkylbladsnamn och formler för definierade namn stannar alltid eftersom de kan ändra arbetsbokens struktur

Datafel som deklarerats av resolvers, division med noll i uttryck och ogiltiga reguljära uttryck använder stabila leverantörs- eller uttryckskategorier; kastade resolver-undantag och alla callback-, avbrotts-, resursgräns-, återställnings-, serialiserings-, säkerhets- och strukturfel förblir fatala

RunToStream, RunToFileoch RunToEncryptedFile stegar serialiseringen inom samma körnings- och datasessionslivstid och publicerar sedan en gång; varje fatal, avbruten, serialiserings-, partiellt strömskrivnings- eller målbytesfel bevarar den kompletta tidigare destinationen och frigör tillfällig lagring innan retur

En icke-tom utdataström måste vara läsbar, skrivbar, storleksändringsbar och sökbar så att återställning kan återställa dess ursprungliga byte, storlek och position; ögonblicksbilder upp till 8 MiB stannar i minnet och större använder hanterad tillfällig lagring, medan en lyckad incheckning lämnar strömmen positionerad i noll

Okrypterad utdata använder den genererade arbetsbokens källformat, så en ODS-mall ger en ODS-ström eller -fil med sin nödvändiga paketmetadata; krypterad utdata fortsätter att använda den krypterade Office-behållaren

ImageProvider bevarar det ursprungliga kompatibilitetskontraktet; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicyoch ClearImageDirectiveCell låter en körare, generator, intervallband eller Excel-tabellband konsumera förkompilerade {{#image Key}} -mål direkt; utelämnas båda leverantörerna lämnas dessa direktivceller oförändrade

AutofitMode (typ TXLSReportAutofitMode) väljer autoanpassning av hela bladet (xramNone, xramRows, xramColumnseller xramBoth) som tillämpas en gång efter att alla mål körts, och AutofitAdjustment är en extra marginalfaktor (1.0 = ingen, 1.1 = 10 % högre rader)

Genereringslivscykel och mallkällor

TXLSReportLifecyclePhase identifierar gränserna för mallavläsning, arbetsboksgenerering och kalkylbladsgenerering, medan TXLSReportLifecycleOutcome skiljer mellan entered-, completed-, canceled- och failed-callbacks

TXLSReportLifecycleContext tillhandahåller den aktiva arbetsboken och arbetsbladet, stabil arbetsbladsidentitet, ursprungliga och aktuella koordinater, en skrivskyddad IXLSReportDataView, antal mål och detaljer om första felet; varje entered before-händelse får en parade after-händelse även när genereringen avbryts eller misslyckas

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheetoch AfterGenerateSheet iakttar en fryst uppsättning ursprungliga arbetsblad; strukturredigeringar från callbacks utlöser omkompilering utan att nyskapade blad läggs till i den aktuella körningen

TXLSReportGenerator accepterar en arbetsbok, ett filnamn, en anropsägd ström eller en krypterad fil och lägger till BeforeReadTemplate plus AfterReadTemplate till genereringshändelserna; TXLSReportModificationMode väljer kompatibel mutering på plats eller isolerad generering via atomär klon. Skrivskyddade SourceKind (typ TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStreameller xrtsEncryptedFile) och TemplateWorkbook rapporterar den konfigurerade mallkällan, medan ModificationMode och IncludeResolver kan ställas in före en körning

Fil- och strömmallar är som standard xrmAtomicClone; sökbara indataströmmar återställer sin ursprungliga position, endast-framåt-strömmar konsumeras i avgränsade block, anroparströmmar förblir öppna, och utdataströmmar eller filer ersatts först efter lyckad fullbordan

Planering, kontroll och migrering

TXLSReportPaginationPlanner tillhandahåller planer KeepTogether, SplitRows, MergeSimilaroch BalanceColumns för fasta sidfötter och balanserad utdata

TXLSReportTemplateChecker tillhandahåller Check, CheckBandoch CheckTableBand; TXLSReportTemplateMigrator tillhandahåller MigrateText och MigrateWorkbook för stödda äldre platshållarformer

Exempel

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

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-exemplet FeatureShowcase och C++Builder-exemplet XlsxFeatureGallery innehåller kompletta körbara versioner som verifierar tillståndet completed-with-errors och problemräkningen innan körningen släpps

Se även

• Avancerade arbetsboksarbetsflöden
• TXLSXWorkbook
• TXLSPaginationModel