API de génération de rapports compilés

L'unité lxReport compile les textes substitutifs et les bandes de rapport structurelles une seule fois, puis applique les données appartenant à l'appelant via des curseurs bornés, sans réanalyser les objets de classeur générés

Contrats de table et de curseur

Fournisseurs de requêtes contrôlés

IXLSReportQueryExecutor.ExecuteReadOnly garde l'exécution des requêtes sous le contrôle de l'hôte et n'accepte que les définitions enregistrées par le code de l'application

TXLSReportQueryParameter, TXLSReportQueryParameterset TXLSReportQueryDefinition exposent Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameteret ClearParameters

TXLSReportQueryProvider utilise RegisterQuery, RemoveQuery, Clearet TryGetTable, avec Count, Definitionset MaximumTimeoutMS exposant la liste blanche et le plafond de délai d'attente

Sessions de données par exécution

IXLSReportDataSession est le cache paresseux isolé derrière une exécution de rapport : DeclareRequest enregistre une TXLSReportDataRequest (type TXLSReportDataRequestKind: xrdrkNamed ou xrdrkUser) dont la TXLSReportDataSource (type TXLSReportDataSourceKind: non spécifié, cellule, bande de plage, bande de table ou expression) et la liste de TXLSReportDataParameter décrivent la source et ses valeurs, et dont RunControl est le handle d'annulation IXLSReportRunControl de l'hôte ; HasResolver teste une clé de fournisseur, TryGetTable et RequireTable lisent les alias en cache, TryResolveTable et RequireResolvedTable résolvent à la demande dans un TXLSReportDataResolveResult (statut TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFoundou xrdrsDataError), et TryGetState signale un TXLSReportDataSessionState parmi chargement, résolu, introuvable ou erreur de données, tandis que CachedAliasCount et ResolvedAliasCount exposent la taille de la session

IXLSReportDataView.TryGetValue recherche une valeur nommée sans lever d'exception, en complément des accesseurs indexés Count, Nameset Values accessors

Relations et combinateurs de tables paresseuses

TXLSReportRowIndexes et TXLSReportRelationIndex conservent les numéros de lignes enfants dans des compartiments à clé composite ; utilisez FindChildRows ou CreateChildCursor et inspectez BucketCount ou IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregateet TXLSReportJoinKind configurent TXLSReportTableFactory, dont les filtres de lignes comparent via TXLSReportFilterOperator (xrfoEqual, xrfoNotEqual, xrfoGreater, xrfoGreaterEqual, xrfoLess, xrfoLessEqual, xrfoContains, xrfoStartsWith, xrfoEndsWith)

Bandes nommées et de plage explicite

TXLSReportBandKind sélectionne l'expansion par ligne, par colonne ou en tableau croisé, et TXLSReportBandState signale l'état du cycle de vie : prêt, en cours, terminé, terminé avec erreurs, annulé ou en échec

TXLSCompiledReportBand accepte un nom défini à portée exacte ou CreateForRange, puis se développe via les surcharges Run ; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCountet State exposent le plan compilé

EmptyBandPolicy (type TXLSEmptyBandPolicy) contrôle ce que la bande fait de ses lignes de modèle quand le jeu de données est vide — xreKeepTemplate laisse les lignes intactes, xreClearTemplate vide les cellules de la bande y compris les textes substitutifs, et xreDeleteTemplate supprime les lignes du modèle — et DeleteLastRow retire les BandHeight dernières lignes du bloc développé une fois ses copies posées, de sorte que les lignes séparatrices X finales disparaissent

FixedBand fait qu'une bande de lignes écrase les lignes situées sous le modèle au lieu d'en insérer de nouvelles, ce qui maintient le contenu environnant à position fixe

Les bandes de plages de lignes et de colonnes clonent des conversations de commentaires en thread quand chaque racine et réponse appartient à la plage de modèle ; les placeholders de texte et de nom d'affichage sont évalués pour chaque enregistrement, les commentaires copiés reçoivent de nouveaux identifiants et des identifiants parents remappés, et les enregistrements de personnes existants du classeur sont réutilisés

La compilation rejette avant expansion les conversations coupées à la frontière du modèle, les parents manquants, les identifiants dupliqués et les ancres de cellules invalides ; le débordement d'ancre est contrôlé avant mutation de la feuille, et une exécution en échec ou annulée supprime les conversations générées tout en restaurant l'état du modèle

TXLSCompiledTableReportBand.Run développe une ligne de modèle de données de table Excel tout en préservant les métadonnées de la table ; inspectez TableName, Sheet, SheetIndex, ExcelTable, TemplateRowet State, et configurez les mêmes propriétés d'image V2 que celles exposées par les bandes de plage

Les bandes de plage et de table Excel partagent ErrorMode, StrictDataAccess, RuntimeLimitset des instantanés LastResult immuables ; xremWriteAndContinue n'écrit comme diagnostics littéraux que les échecs de cellule explicitement récupérables, enregistre la BandInputRow source et les coordonnées de sortie réelles, puis poursuit les cibles et lignes suivantes, tandis que les échecs structurels, d'annulation, de limite de ressources, de callback et de rollback restent fatals

TXLSCompiledSheetReportBand.Run crée des feuilles par enregistrement à l'aide de NameColumn, NamePrefixet DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run crée des feuilles de continuation à l'aide de NamePrefix et DeleteTemplateAfterRun

Modèles de classeur entier

TXLSReportTemplateTarget et TXLSReportTemplateTargets sélectionnent les cellules, commentaires, hyperliens, formes, en-têtes et pieds de page, noms de feuilles, noms définis et propriétés de document

TXLSCompiledReportTemplate.Compile capture les cibles et les expressions, Analyze renvoie des TXLSReportIssuesadressés, les surcharges Run appliquent les valeurs et WriteDiagnostics écrit les problèmes dans une feuille de calcul ; TargetAreas, TargetCountet UserTableCount décrivent la surface compilée et les tables utilisateur enregistrées

ProcessStructuralDirectives ( Truepar défaut) fait qu'un Run de modèle exécute les directives structurelles {{#delete}} et {{#format}} après l'application des cibles de valeurs — le TXLSReportDirectiveProcessor qui en charge analyse les plages, les applique et indique combien il en a traitées via AppliedCount — et CreateEncrypted ouvre un modèle chiffré avec son mot de passe et le compile tout en gardant le classeur accessible via la propriété Workbook property

TXLSReportIssueKind, TXLSReportIssueet TXLSReportIssues identifient le contenu de texte substitutif malformé, manquant, invalide, inconnu ou cyclique avec les coordonnées de cible et de cellule

Inclusions, images et mise en forme

IXLSReportIncludeResolver.Resolve fournit des fragments nommés et son indicateur Immutable permet une réutilisation sûre ; TXLSReportIncludeLibrary fournit Add, Remove, Clear, Freeze, Resolve, Countet Immutable

IXLSReportImageProvider.TryGetImage renvoie une TXLSReportImageValue configurée par TXLSReportImageFit; TXLSReportMissingImagePolicy contrôle les ressources manquantes, tandis que TXLSReportImageBinder.Apply, ApplyTarget, MissingPolicyet ClearDirectiveCell mettent à jour les directives d'image exactes

TXLSReportImageBinder.ApplyTargetV2 lie une cellule de directive via le contrat de fournisseur V2 et transmet un TXLSReportTransformImageEvent capable de réécrire la charge utile résolue avant son dépôt ; le texte substitutif résolu est lui-même un TXLSReportEvaluatedTarget dont le TXLSReportEvaluatedTargetKind distingue xretNone, xretText, xretValueet xretFormula; IXLSReportImageCancellation.IsCancellationRequested permet aux fournisseurs longs à exécuter d'observer une annulation coopérative

IXLSReportImageDataProviderV2.GetImage reçoit une TXLSReportImageRequest avec l'identité stable de la feuille de calcul, la cible compilée, les noms de bande et de table, les lignes logique et curseur, une vue en lecture seule de la ligne courante, les cellules de directive et d'ancrage, les dimensions et décalages de la cible en EMU, et IXLSReportImageCancellation

TXLSReportImageResult transporte une TXLSReportImagePayload dont Kind (TXLSReportImagePayloadKind) sélectionne xripMissing, des octets ou un flux, la durée de vie du flux étant déclarée par TXLSReportImageStreamOwnership: les flux xrisoBorrowed restent la propriété de l'appelant et restaurent leur position s'ils sont positionnables, tandis que les flux xrisoTransferred sont libérés exactement une fois ; les SourceWidth, SourceHeight, SourceDpiXet SourceDpiY facultatifs affirment ou redéfinissent la géométrie physique de la source

xrifNatural utilise la taille physique de la source, xrifContain met à l'échelle et centre dans la boîte cible, xrifCover remplit la boîte avec un rognage symétrique de la source, et xrifStretch la remplit sans préserver les proportions ; la géométrie PNG, JPEG, GIF, BMP, EMF et WMF est lue dans des en-têtes bornés sans décoder les pixels

OnTransformImage s'exécute après l'instantané des données du fournisseur et avant la mutation de la feuille de calcul ; MaximumImageBytes vaut 64 MiB par défaut et les signatures de charge utile, en-têtes de géométrie, paires dimension et DPI, limites de côté raster et de pixels, ancres et coordonnées de grille sont validées avant la liaison

TXLSXImage.OffsetXEMU et OffsetYEMU conservent la position d'une image dans sa cellule ou son ancrage absolu lors des allers-retours XLSX et ODS

TXLSReportDynamicFormat et TXLSReportFormatEvent permettent à un exécuteur d'appliquer des formats de nombres, des hauteurs de lignes et des largeurs de colonnes par cible

Exécution réutilisable

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgresset TXLSReportRunProgressEvent décrivent les limites de progression et d'annulation

TXLSCompiledReportRunner expose Run, RunToStream, RunToFile, RunToEncryptedFileet Cancel, avec ReportTemplate, State, Progress, OnProgresset OnFormat contrôlant l'exécution réutilisable ; une validation échouée lève EXLSReportData avant les écritures déterministes

ErrorMode (type TXLSReportErrorMode) vaut xremStoppar défaut ; xremWriteAndContinue ne traite que les échecs EXLSReportRecoverableData explicites et les résultats DataError des résolveurs, enregistre des problèmes immuables ordonnés dans LastResult (un IXLSReportRunResult exposant State, AppliedCount, IssueCount, Issuesindexés, et le FailureClassName / FailureMessage d'un échec fatal) dont les instantanés TXLSReportRuntimeIssue exposent leur Category (un TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProviderou xrricExpression) et signalent TargetIndex, SheetName, Colet si le problème était déjà WasWritten dans la sortie, et se termine en xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults autorise 100 000 problèmes retenus, 512 caractères par message assaini et 16 MiB de mémoire de problèmes ; affectez un enregistrement RuntimeLimits personnalisé positif avant une exécution, et laissez RuntimeDiagnosticsSheetName vide sauf si une feuille de diagnostics structurée est requise

Les valeurs de cellules et formules récupérables deviennent un texte littéral [Report error CODE] message , les cibles non cellulaires sûres conservent leur valeur d'origine, et une feuille de diagnostics facultative marque ces problèmes structurés comme écrits ; les échecs de nom de feuille et de formule de nom défini s'arrêtent toujours car ils peuvent modifier la structure du classeur

Les erreurs de données déclarées par les résolveurs, les divisions par zéro d'expressions et les expressions régulières invalides utilisent des catégories stables de fournisseur ou d'expression ; les exceptions levées par les résolveurs et tous les échecs de callback, d'annulation, de limite de ressources, de rollback, de sérialisation, de sécurité et structurels restent fatals

RunToStream, RunToFileet RunToEncryptedFile préparent la sérialisation dans la même durée de vie d'exécution et de session de données, puis publient une seule fois ; tout échec fatal, d'annulation, de sérialisation, d'écriture partielle de flux ou de remplacement de destination préserve la destination antérieure complète et libère le stockage temporaire avant de retourner

Un flux de sortie non vide doit être lisible, inscriptible, redimensionnable et positionnable pour que le rollback puisse restaurer ses octets, sa taille et sa position d'origine ; les instantanés jusqu'à 8 MiB restent en mémoire et les plus grands utilisent un stockage temporaire géré, tandis qu'un commit réussi laisse le flux positionné à zéro

La sortie non chiffrée utilise le format source du classeur généré, si bien qu'un modèle ODS produit un flux ou un fichier ODS avec ses métadonnées de package requises ; la sortie chiffrée continue d'utiliser le conteneur Office chiffré

ImageProvider préserve le contrat de compatibilité d'origine ; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicyet ClearImageDirectiveCell permettent à un exécuteur, un générateur, une bande de plage ou une bande de table Excel de consommer directement des cibles {{#image Key}} précompilées ; omettre les deux fournisseurs laisse ces cellules de directive inchangées

AutofitMode (type TXLSReportAutofitMode) sélectionne un ajustement automatique de feuille entière (xramNone, xramRows, xramColumnsou xramBoth) appliqué une fois après l'exécution de toutes les cibles, et AutofitAdjustment est un facteur de marge supplémentaire (1.0 = aucun, 1.1 = lignes 10 % plus hautes)

Cycle de vie de génération et sources de modèles

TXLSReportLifecyclePhase identifie les frontières de lecture du modèle, de génération du classeur et de génération de feuille de calcul, tandis que TXLSReportLifecycleOutcome distingue les callbacks entrés, terminés, annulés et en échec

TXLSReportLifecycleContext fournit le classeur et la feuille de calcul actifs, l'identité stable de la feuille, les coordonnées d'origine et courantes, une IXLSReportDataViewen lecture seule, le nombre de cibles et les détails du premier échec ; chaque événement avant entré reçoit un événement après apparié, même lorsque la génération est annulée ou échoue

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheetet AfterGenerateSheet observent un ensemble figé de feuilles de calcul d'origine ; les changements de structure pilotés par callback déclenchent un rafraîchissement de compilation sans ajouter les feuilles nouvellement créées à l'exécution en cours

TXLSReportGenerator accepte un classeur, un nom de fichier, un flux détenu par l'appelant ou un fichier chiffré et ajoute BeforeReadTemplate plus AfterReadTemplate aux événements de génération ; TXLSReportModificationMode sélectionne une mutation sur place compatible ou une génération par clone atomique isolé. Le SourceKind en lecture seule (type TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStreamou xrtsEncryptedFile) et TemplateWorkbook signalent la source de modèle configurée, tandis que ModificationMode et IncludeResolver sont paramétrables avant une exécution

Les modèles fichier et flux prennent xrmAtomicClonepar défaut ; les flux d'entrée positionnables restaurent leur position d'origine, les flux en parcours avant unique sont consommés par blocs bornés, les flux de l'appelant restent ouverts, et les flux ou fichiers de sortie ne sont remplacés qu'après une complétion réussie

Planification, vérification et migration

TXLSReportPaginationPlanner fournit les plans KeepTogether, SplitRows, MergeSimilaret BalanceColumns pour les pieds de page fixes et une sortie équilibrée

TXLSReportTemplateChecker fournit Check, CheckBandet CheckTableBand; TXLSReportTemplateMigrator fournit MigrateText et MigrateWorkbook pour les formes héritées de texte substitutif prises en charge

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

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

Les versions entièrement exécutables Delphi FeatureShowcase et C++Builder XlsxFeatureGallery vérifient l'état terminé-avec-erreurs et le nombre de problèmes avant de libérer l'exécuteur

Voir aussi

• Flux de travail avancés de classeur
• TXLSXWorkbook
• TXLSPaginationModel