API di reporting compilato

L'unità lxReport compila una volta i segnaposto e le bande di report strutturali, quindi applica i dati di proprietà del chiamante tramite cursori limitati senza riesaminare gli oggetti della cartella di lavoro generata

Contratti di tabella e cursore

Provider di query controllati

IXLSReportQueryExecutor.ExecuteReadOnly mantiene l'esecuzione delle query di proprietà dell'host e accetta solo definizioni registrate dal codice applicativo

TXLSReportQueryParameter, TXLSReportQueryParameterse TXLSReportQueryDefinition espongono Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParametere ClearParameters

TXLSReportQueryProvider usa RegisterQuery, RemoveQuery, Cleare TryGetTable, con Count, Definitionse MaximumTimeoutMS che espongono la whitelist e il tetto massimo di timeout

Sessioni dati per esecuzione

IXLSReportDataSession è la cache lazy isolata alla base di una singola esecuzione del report: DeclareRequest registra una TXLSReportDataRequest (tipo TXLSReportDataRequestKind: xrdrkNamed o xrdrkUser) la cui TXLSReportDataSource (tipo TXLSReportDataSourceKind: non specificato, cella, banda di intervallo, banda di tabella o espressione) e la lista di TXLSReportDataParameter descrivono la sorgente e i suoi valori, e il cui RunControl è l'handle di cancellazione IXLSReportRunControl dell'host; HasResolver verifica una chiave di provider, TryGetTable e RequireTable leggono gli alias in cache, TryResolveTable e RequireResolvedTable risolvono on demand in un TXLSReportDataResolveResult (stato TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFoundo xrdrsDataError), e TryGetState riporta uno TXLSReportDataSessionState tra caricamento, risolto, non trovato o errore dati, mentre CachedAliasCount e ResolvedAliasCount espongono la dimensione della sessione

IXLSReportDataView.TryGetValue cerca un singolo valore denominato senza sollevare eccezioni, completando gli accessor indicizzati Count, Namese Values accessors

Relazioni e combinatori di tabelle lazy

TXLSReportRowIndexes e TXLSReportRelationIndex conservano i numeri di riga figli in bucket a chiave composta; usare FindChildRows o CreateChildCursor e ispezionare BucketCount o IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregatee TXLSReportJoinKind configurano TXLSReportTableFactory, i cui filtri di riga confrontano tramite TXLSReportFilterOperator (xrfoEqual, xrfoNotEqual, xrfoGreater, xrfoGreaterEqual, xrfoLess, xrfoLessEqual, xrfoContains, xrfoStartsWith, xrfoEndsWith)

Bande di intervallo denominate ed esplicite

TXLSReportBandKind seleziona l'espansione per riga, colonna o tabella incrociata, e TXLSReportBandState riporta lo stato del ciclo di vita: pronto, in esecuzione, completato, completato-con-errori, annullato o fallito

TXLSCompiledReportBand accetta un nome definito a ambito esatto o CreateForRange, quindi si espande tramite gli overload di Run ; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCounte State espongono il piano compilato

EmptyBandPolicy (tipo TXLSEmptyBandPolicy) controlla cosa fa la banda con le sue righe modello quando il set di dati è vuoto — xreKeepTemplate lascia le righe intatte, xreClearTemplate svuota le celle della banda compresi i segnaposto e xreDeleteTemplate elimina le righe modello — e DeleteLastRow rimuove le ultime BandHeight righe del blocco espanso dopo che le sue copie sono state scritte, così le righe separatore X-finali collassano

FixedBand fa sì che le bande di riga sovrascrivano le righe sotto il modello invece di inserirne di nuove, mantenendo il contenuto circostante a posizione fissa

Le bande di intervallo di righe e colonne clonano le conversazioni di commenti in thread quando ogni root e reply appartiene all'intervallo del modello; i segnaposto di testo e nome visualizzato vengono valutati per ogni record, i commenti copiati ricevono nuovi identificatori e identificatori di parent rimappati, e i record di persona esistenti del workbook vengono riutilizzati

La compilazione rifiuta conversazioni divise attraverso il confine del modello, parent mancanti, identificatori duplicati e ancore di cella non valide prima dell'espansione; l'overflow dell'ancora viene verificato prima della mutazione del foglio di lavoro, e un'esecuzione fallita o annullata rimuove le conversazioni generate ripristinando lo stato del modello

TXLSCompiledTableReportBand.Run espande una riga modello di tabella Excel preservando i metadati della tabella; ispezionare TableName, Sheet, SheetIndex, ExcelTable, TemplateRowe State, e configurare le stesse proprietà immagine V2 esposte dalle bande di intervallo

Le bande di intervallo e di tabella Excel condividono ErrorMode, StrictDataAccess, RuntimeLimitse istantanee immutabili di LastResult ; xremWriteAndContinue scrive come diagnostica letterale solo gli espliciti errori recoverabili di singola cella, registra la BandInputRow sorgente e le coordinate di output effettive e prosegue con destinazioni e righe successive, mentre i guasti strutturali, di annullamento, di limite di risorse, di callback e di rollback restano fatali

TXLSCompiledSheetReportBand.Run crea fogli per record usando NameColumn, NamePrefixe DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run crea fogli di continuazione usando NamePrefix e DeleteTemplateAfterRun

Modelli a livello di cartella di lavoro

TXLSReportTemplateTarget e TXLSReportTemplateTargets selezionano celle, commenti, collegamenti ipertestuali, forme, intestazioni e piè di pagina, nomi di foglio, nomi definiti e proprietà del documento

TXLSCompiledReportTemplate.Compile acquisisce destinazioni ed espressioni, Analyze restituisce TXLSReportIssuesindicizzate, gli overload di Run applicano i valori e WriteDiagnostics scrive i problemi in un foglio di lavoro; TargetAreas, TargetCounte UserTableCount descrivono la superficie compilata e le tabelle utente registrate

ProcessStructuralDirectives (predefinito True) fa sì che il Run di un modello esegua le direttive strutturali {{#delete}} e {{#format}} dopo l'applicazione delle destinazioni di valore — il TXLSReportDirectiveProcessor sottostante analizza gli intervalli, li applica e riporta quanti ne ha gestiti tramite AppliedCount — e CreateEncrypted apre un modello cifrato con la sua password e lo compila mantenendo la cartella di lavoro raggiungibile tramite la proprietà Workbook property

TXLSReportIssueKind, TXLSReportIssuee TXLSReportIssues identificano contenuti segnaposto malformati, mancanti, non validi, sconosciuti o ciclici con coordinate di destinazione e cella

Inclusioni, immagini e formattazione

IXLSReportIncludeResolver.Resolve fornisce frammenti denominati e il suo flag Immutable consente un riutilizzo sicuro; TXLSReportIncludeLibrary fornisce Add, Remove, Clear, Freeze, Resolve, Counte Immutable

IXLSReportImageProvider.TryGetImage restituisce un TXLSReportImageValue configurato da TXLSReportImageFit; TXLSReportMissingImagePolicy controlla le risorse mancanti, mentre TXLSReportImageBinder.Apply, ApplyTarget, MissingPolicye ClearDirectiveCell aggiornano le direttive immagine esatte

TXLSReportImageBinder.ApplyTargetV2 collega una cella direttiva tramite il contratto di provider V2 e inoltra un TXLSReportTransformImageEvent che può riscrivere il payload risolto prima che venga scritto; il segnaposto risolto è esso stesso un TXLSReportEvaluatedTarget il cui TXLSReportEvaluatedTargetKind distingue xretNone, xretText, xretValuee xretFormula; IXLSReportImageCancellation.IsCancellationRequested permette ai provider di lunga durata di osservare una cancellazione cooperativa

IXLSReportImageDataProviderV2.GetImage riceve una TXLSReportImageRequest con identità stabile del foglio di lavoro, destinazione compilata, nomi di banda e di tabella, righe logica e del cursore, una vista della riga corrente in sola lettura, celle direttiva e di ancoraggio, dimensioni e offset della destinazione in EMU e IXLSReportImageCancellation

TXLSReportImageResult trasporta un TXLSReportImagePayload il cui Kind (TXLSReportImagePayloadKind) seleziona xripMissing, byte o uno stream, con la durata dello stream dichiarata da TXLSReportImageStreamOwnership: gli stream xrisoBorrowed restano di proprietà del chiamante e ripristinano la posizione se seekable, mentre gli stream xrisoTransferred vengono rilasciati esattamente una volta; i campi opzionali SourceWidth, SourceHeight, SourceDpiXe SourceDpiY dichiarano o sovrascrivono la geometria fisica della sorgente

xrifNatural usa la dimensione fisica della sorgente, xrifContain scala e centra dentro il box di destinazione, xrifCover riempie il box con un ritaglio simmetrico della sorgente e xrifStretch lo riempie senza preservare le proporzioni; la geometria di PNG, JPEG, GIF, BMP, EMF e WMF viene letta da header limitati senza decodificare i pixel

OnTransformImage gira dopo lo snapshot dei dati del provider e prima della mutazione del foglio di lavoro; MaximumImageBytes è 64 MiB per default e firme dei payload, header di geometria, coppie dimensione/DPI, limiti raster di lato e pixel, ancore e coordinate della griglia vengono validati prima del binding

TXLSXImage.OffsetXEMU e OffsetYEMU conservano la posizione di un'immagine dentro la sua cella o l'ancoraggio assoluto attraverso i round-trip XLSX e ODS

TXLSReportDynamicFormat e TXLSReportFormatEvent consentono a un runner di applicare formati numerici, altezze di riga e larghezze di colonna per destinazione

Esecuzione riutilizzabile

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgresse TXLSReportRunProgressEvent descrivono i confini di avanzamento e annullamento

TXLSCompiledReportRunner espone Run, RunToStream, RunToFile, RunToEncryptedFilee Cancel, con ReportTemplate, State, Progress, OnProgresse OnFormat che controllano l'esecuzione riutilizzabile; una convalida non riuscita genera EXLSReportData prima delle scritture deterministiche

ErrorMode (tipo TXLSReportErrorMode) è xremStopper default; xremWriteAndContinue gestisce solo gli espliciti guasti EXLSReportRecoverableData e i risultati DataError dei resolver, registra problemi immutabili ordinati in LastResult (un IXLSReportRunResult che espone State, AppliedCount, IssueCount, le Issuesindicizzate e FailureClassName / FailureMessage di un guasto fatale) le cui istantanee TXLSReportRuntimeIssue espongono la propria Category (un TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProvidero xrricExpression) e riportano TargetIndex, SheetName, Cole se il problema era già stato WasWritten nell'output, e termina come xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults consente 100.000 problemi trattenuti, 512 caratteri per messaggio sanificato e 16 MiB di memoria per i problemi; assegnare un record RuntimeLimits personalizzato positivo prima dell'esecuzione, e lasciare RuntimeDiagnosticsSheetName vuoto a meno che non serva un foglio di diagnostica strutturato

I valori di cella e le formule recoverabili diventano testo letterale [Report error CODE] message , le destinazioni non-cell sicure conservano il loro valore originale e un eventuale foglio di diagnostica marca quei problemi strutturati come scritti; i guasti su nomi di foglio e formule di nomi definiti fermano sempre, perché possono cambiare la struttura della cartella di lavoro

Gli errori dati dichiarati dai resolver, le divisioni per zero nelle espressioni e le espressioni regolari non valide usano categorie stabili di provider o di espressione; le eccezioni lanciate dai resolver e tutti i guasti di callback, annullamento, limite di risorse, rollback, serializzazione, sicurezza e struttura restano fatali

RunToStream, RunToFilee RunToEncryptedFile mettono in scena la serializzazione dentro la stessa durata di esecuzione e sessione dati, poi pubblicano una sola volta; qualsiasi guasto fatale, annullamento, serializzazione, scrittura parziale dello stream o sostituzione della destinazione preserva la destinazione precedente completa e rilascia lo storage temporaneo prima di restituire

Uno stream di output non vuoto deve essere leggibile, scrivibile, ridimensionabile e seekable, così il rollback può ripristinarne byte, dimensione e posizione originali; le istantanee fino a 8 MiB restano in memoria e quelle maggiori usano storage temporaneo gestito, mentre un commit riuscito lascia lo stream posizionato a zero

L'output non cifrato usa il formato sorgente della cartella di lavoro generata, quindi un modello ODS produce uno stream o file ODS con i suoi metadati di pacchetto richiesti; l'output cifrato continua a usare il contenitore Office cifrato

ImageProvider preserva il contratto di compatibilità originale; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicye ClearImageDirectiveCell permettono a un runner, generatore, banda di intervallo o banda di tabella Excel di consumare direttamente le destinazioni precompilate {{#image Key}} ; omettendo entrambi i provider le celle di quelle direttive restano invariate

AutofitMode (tipo TXLSReportAutofitMode) seleziona un autofit dell'intero foglio (xramNone, xramRows, xramColumnso xramBoth) applicato una sola volta dopo l'esecuzione di tutte le destinazioni, e AutofitAdjustment è un fattore extra di margine (1.0 = nessuno, 1.1 = righe più alte del 10%)

Ciclo di vita della generazione e sorgenti dei modelli

TXLSReportLifecyclePhase identifica i confini di lettura del modello, generazione della cartella di lavoro e generazione del foglio di lavoro, mentre TXLSReportLifecycleOutcome distingue callback entrati, completati, annullati e falliti

TXLSReportLifecycleContext fornisce la cartella di lavoro e il foglio di lavoro attivi, l'identità stabile del foglio, le coordinate originali e correnti, una IXLSReportDataViewin sola lettura, il numero di destinazioni e i dettagli del primo guasto; ogni evento before entrato riceve un evento after abbinato anche quando la generazione viene annullata o fallisce

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheete AfterGenerateSheet osservano un insieme congelato dei fogli di lavoro originali; le modifiche strutturali guidate da callback innescano un refresh della compilazione senza aggiungere i fogli appena creati all'esecuzione corrente

TXLSReportGenerator accetta una cartella di lavoro, un nome file, uno stream di proprietà del chiamante o un file cifrato e aggiunge BeforeReadTemplate più AfterReadTemplate agli eventi di generazione; TXLSReportModificationMode seleziona la mutazione in-place compatibile o la generazione isolata per clone atomico. SourceKind in sola lettura (tipo TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStreamo xrtsEncryptedFile) e TemplateWorkbook riportano la sorgente del modello configurata, mentre ModificationMode e IncludeResolver sono impostabili prima dell'esecuzione

I modelli da file e stream usano xrmAtomicCloneper default; gli stream di input seekable ripristinano la loro posizione originale, gli stream forward-only vengono consumati a blocchi limitati, gli stream del chiamante restano aperti e gli stream o file di output vengono sostituiti solo dopo il completamento riuscito

Pianificazione, verifica e migrazione

TXLSReportPaginationPlanner fornisce i piani KeepTogether, SplitRows, MergeSimilare BalanceColumns per piè di pagina fissi e output bilanciato

TXLSReportTemplateChecker fornisce Check, CheckBande CheckTableBand; TXLSReportTemplateMigrator fornisce MigrateText e MigrateWorkbook per le forme di segnaposto legacy supportate

Esempio 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;

Esempio 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;

Le demo FeatureShowcase per Delphi e XlsxFeatureGallery per C++Builder contengono versioni complete eseguibili che verificano lo stato completato-con-errori e il numero di problemi prima di rilasciare il runner

Vedere anche

• Flussi di lavoro avanzati della cartella di lavoro
• TXLSXWorkbook
• TXLSPaginationModel