API de informes compilados

La unidad lxReport compila los marcadores de posición y las bandas de informe estructurales una sola vez y luego aplica los datos propiedad del llamador mediante cursores acotados, sin volver a examinar los objetos de libro generados

Contratos de tabla y cursor

Proveedores de consulta controlados

IXLSReportQueryExecutor.ExecuteReadOnly mantiene la ejecución de consultas en manos del host y solo acepta definiciones registradas por el código de la aplicación

TXLSReportQueryParameter, TXLSReportQueryParameters, and TXLSReportQueryDefinition exponen Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParametery ClearParameters

TXLSReportQueryProvider usa RegisterQuery, RemoveQuery, Cleary TryGetTable, con Count, Definitionsy MaximumTimeoutMS que exponen la lista blanca y el techo de tiempo de espera

Sesiones de datos por ejecución

IXLSReportDataSession es la caché diferida aislada detrás de una ejecución de informe: DeclareRequest registra un TXLSReportDataRequest (de tipo TXLSReportDataRequestKind: xrdrkNamed o xrdrkUser) cuyo TXLSReportDataSource (de tipo TXLSReportDataSourceKind: sin especificar, celda, banda de rango, banda de tabla o expresión) y lista de TXLSReportDataParameter describen la fuente y sus valores, y cuyo RunControl es el manejador de cancelación IXLSReportRunControl del host; HasResolver comprueba una clave de proveedor, TryGetTable y RequireTable leen alias cacheados, TryResolveTable y RequireResolvedTable resuelven bajo demanda en un TXLSReportDataResolveResult (estado TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFoundo xrdrsDataError), y TryGetState informa de un TXLSReportDataSessionState de cargando, resuelto, no encontrado o error de datos, mientras que CachedAliasCount y ResolvedAliasCount exponen el tamaño de la sesión

IXLSReportDataView.TryGetValue busca un valor con nombre sin lanzar excepciones, complementando los accesores indexados Count, Namesy Values accessors

Relaciones y combinadores de tablas diferidas

TXLSReportRowIndexes and TXLSReportRelationIndex conservan los números de fila secundaria en cubos de clave compuesta; use FindChildRows o CreateChildCursor e inspeccione BucketCount o IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregate, and TXLSReportJoinKind configuran TXLSReportTableFactory, cuyos filtros de fila comparan mediante TXLSReportFilterOperator (xrfoEqual, xrfoNotEqual, xrfoGreater, xrfoGreaterEqual, xrfoLess, xrfoLessEqual, xrfoContains, xrfoStartsWith, xrfoEndsWith)

Bandas de rango con nombre y explícitas

TXLSReportBandKind selecciona la expansión por filas, columnas o tablas cruzadas, y TXLSReportBandState informa del estado del ciclo de vida: listo, en ejecución, completado, completado con errores, cancelado o fallido

TXLSCompiledReportBand acepta un nombre definido de ámbito exacto o CreateForRangey luego se expande mediante las sobrecargas de Run ; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCounty State exponen el plan compilado

EmptyBandPolicy (de tipo TXLSEmptyBandPolicy) controla qué hace la banda con sus filas de plantilla cuando el conjunto de datos está vacío: xreKeepTemplate deja las filas intactas, xreClearTemplate borra las celdas de la banda incluidos los marcadores de posición y xreDeleteTemplate elimina las filas de plantilla; y DeleteLastRow elimina las últimas BandHeight filas del bloque expandido después de que aterrizan sus copias, de modo que las filas separadoras del rango X final se colapsan

FixedBand hace que las bandas de fila sobrescriban las filas situadas bajo la plantilla en lugar de insertar otras nuevas, lo que mantiene el contenido circundante en una posición fija

Las bandas de rango de filas y columnas clonan las conversaciones de comentarios encadenados cuando cada comentario raíz y cada respuesta pertenecen al rango de plantilla; los marcadores de posición de texto y de nombre mostrado se evalúan para cada registro, los comentarios copiados reciben nuevos identificadores e identificadores primarios reasignados, y los registros de personas existentes del libro se reutilizan

La compilación rechaza antes de la expansión las conversaciones divididas a través del límite de la plantilla, los comentarios primarios ausentes, los identificadores duplicados y los anclajes de celda no válidos; el desbordamiento de anclajes se comprueba antes de mutar la hoja de cálculo, y una ejecución fallida o cancelada elimina las conversaciones generadas mientras restaura el estado de la plantilla

TXLSCompiledTableReportBand.Run expande una fila de plantilla de datos de una tabla de Excel conservando los metadatos de la tabla; inspeccione TableName, Sheet, SheetIndex, ExcelTable, TemplateRowy State, y configure las mismas propiedades de imagen V2 que exponen las bandas de rango

Las bandas de rango y de tabla de Excel comparten ErrorMode, StrictDataAccess, RuntimeLimitse instantáneas LastResult inmutables; xremWriteAndContinue escribe como diagnósticos literales solo los fallos de celda recuperables explícitos, registra la BandInputRow de origen y las coordenadas de salida reales, y continúa con los objetivos y filas posteriores, mientras que los fallos estructurales, de cancelación, de límite de recursos, de devolución de llamada y de reversión siguen siendo fatales

TXLSCompiledSheetReportBand.Run crea hojas por registro mediante NameColumn, NamePrefixy DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run crea hojas de continuación mediante NamePrefix y DeleteTemplateAfterRun

Plantillas de libro completo

TXLSReportTemplateTarget and TXLSReportTemplateTargets seleccionan celdas, comentarios, hipervínculos, formas, encabezados y pies de página, nombres de hoja, nombres definidos y propiedades de documento

TXLSCompiledReportTemplate.Compile captura objetivos y expresiones, Analyze devuelve TXLSReportIssuescon direcciones, las sobrecargas de Run aplican valores y WriteDiagnostics escribe los problemas en una hoja de cálculo; TargetAreas, TargetCounty UserTableCount describen la superficie compilada y las tablas de usuario registradas

ProcessStructuralDirectives (predeterminado True) hace que el Run de una plantilla ejecute las directivas estructurales {{#delete}} y {{#format}} después de aplicar los objetivos de valor (el TXLSReportDirectiveProcessor que hay detrás analiza los rangos, los aplica e informa de cuántos ha gestionado mediante AppliedCount ), y CreateEncrypted abre una plantilla cifrada con su contraseña y la compila manteniendo el libro accesible a través de la propiedad Workbook property

TXLSReportIssueKind, TXLSReportIssue, and TXLSReportIssues identifican contenido de marcador de posición mal formado, ausente, no válido, desconocido o cíclico, con coordenadas de objetivo y celda

Inclusiones, imágenes y formato

IXLSReportIncludeResolver.Resolve suministra fragmentos con nombre y su indicador Immutable permite la reutilización segura; TXLSReportIncludeLibrary proporciona Add, Remove, Clear, Freeze, Resolve, Counte Immutable

IXLSReportImageProvider.TryGetImage devuelve un TXLSReportImageValue configurado por TXLSReportImageFit; TXLSReportMissingImagePolicy controla los recursos ausentes, mientras que TXLSReportImageBinder.Apply, ApplyTarget, MissingPolicyy ClearDirectiveCell actualizan directivas de imagen exactas

TXLSReportImageBinder.ApplyTargetV2 vincula una celda de directiva mediante el contrato de proveedor V2 y reenvía un TXLSReportTransformImageEvent que puede reescribir la carga resuelta antes de que aterrice; el propio marcador de posición resuelto es un TXLSReportEvaluatedTarget cuyo TXLSReportEvaluatedTargetKind distingue xretNone, xretText, xretValuey xretFormula; IXLSReportImageCancellation.IsCancellationRequested permite a los proveedores de larga duración observar una cancelación cooperativa

IXLSReportImageDataProviderV2.GetImage recibe un TXLSReportImageRequest con identidad estable de hoja de cálculo, objetivo compilado, nombres de banda y tabla, filas lógica y de cursor, una vista de solo lectura de la fila actual, celdas de directiva y anclaje, dimensiones y desplazamientos del objetivo en EMU, y IXLSReportImageCancellation

TXLSReportImageResult transporta un TXLSReportImagePayload cuyo Kind (TXLSReportImagePayloadKind) selecciona xripMissing, bytes o un flujo, con el ciclo de vida del flujo declarado por TXLSReportImageStreamOwnership: los flujos xrisoBorrowed siguen siendo propiedad del llamador y restauran su posición si son posicionables, mientras que los flujos xrisoTransferred se liberan exactamente una vez; los opcionales SourceWidth, SourceHeight, SourceDpiXy SourceDpiY afirman o sobrescriben la geometría física del origen

xrifNatural usa el tamaño físico del origen, xrifContain escala y centra dentro del cuadro de destino, xrifCover llena el cuadro con un recorte simétrico del origen y xrifStretch lo llena sin conservar la relación de aspecto; la geometría de PNG, JPEG, GIF, BMP, EMF y WMF se lee de cabeceras acotadas sin descodificar píxeles

OnTransformImage se ejecuta después de tomar la instantánea de los datos del proveedor y antes de mutar la hoja de cálculo; MaximumImageBytes tiene 64 MiB por defecto, y las firmas de carga, cabeceras de geometría, pares de dimensión y DPI, límites de lado ráster y de píxeles, anclajes y coordenadas de cuadrícula se validan antes del enlace

TXLSXImage.OffsetXEMU and OffsetYEMU conservan la posición de una imagen dentro de su celda o anclaje absoluto en los round-trips de XLSX y ODS

TXLSReportDynamicFormat and TXLSReportFormatEvent permiten que un ejecutor aplique formatos de número, alturas de fila y anchos de columna por objetivo

Ejecución reutilizable

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgress, and TXLSReportRunProgressEvent describen los límites de progreso y cancelación

TXLSCompiledReportRunner expone Run, RunToStream, RunToFile, RunToEncryptedFiley Cancel, con ReportTemplate, State, Progress, OnProgressy OnFormat que controlan la ejecución reutilizable; la validación fallida lanza EXLSReportData antes de las escrituras deterministas

ErrorMode (de tipo TXLSReportErrorMode) es xremStoppor defecto; xremWriteAndContinue gestiona solo fallos explícitos EXLSReportRecoverableData y resultados DataError de resolutores, registra problemas inmutables ordenados en LastResult (un IXLSReportRunResult que expone State, AppliedCount, IssueCount, Issuesindexados y el FailureClassName / FailureMessage de un fallo fatal), cuyas instantáneas TXLSReportRuntimeIssue exponen su Category (un TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProvidero xrricExpression) e informan de TargetIndex, SheetName, Coly de si el problema ya fue WasWritten en la salida, y termina como xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults permite 100.000 problemas retenidos, 512 caracteres por mensaje saneado y 16 MiB de memoria de problemas; asigne un registro RuntimeLimits personalizado positivo antes de una ejecución y deje RuntimeDiagnosticsSheetName vacío salvo que se necesite una hoja de diagnóstico estructurada

Los valores y fórmulas de celda recuperables se convierten en texto literal [Report error CODE] message , los objetivos seguros fuera de celdas conservan su valor original, y una hoja de diagnóstico opcional marca esos problemas estructurados como escritos; los fallos de nombre de hoja y de fórmula de nombre definido siempre detienen la ejecución porque pueden cambiar la estructura del libro

Los errores de datos declarados por resolutores, la división por cero en expresiones y las expresiones regulares no válidas usan categorías estables de proveedor o de expresión; las excepciones lanzadas por resolutores y todos los fallos de devolución de llamada, cancelación, límite de recursos, reversión, serialización, seguridad y estructurales siguen siendo fatales

RunToStream, RunToFile, and RunToEncryptedFile preparan la serialización dentro del mismo ciclo de vida de ejecución y sesión de datos y luego publican una sola vez; cualquier fallo fatal, de cancelación, de serialización, de escritura parcial del flujo o de reemplazo del destino preserva el destino previo completo y libera el almacenamiento temporal antes de retornar

Un flujo de salida no vacío debe ser legible, escribible, redimensionable y posicionable para que la reversión pueda restaurar sus bytes, tamaño y posición originales; las instantáneas de hasta 8 MiB permanecen en memoria y las más grandes usan almacenamiento temporal gestionado, mientras que una confirmación exitosa deja el flujo posicionado en cero

La salida sin cifrar usa el formato de origen del libro generado, de modo que una plantilla ODS produce un flujo o archivo ODS con sus metadatos de paquete requeridos; la salida cifrada sigue usando el contenedor cifrado de Office

ImageProvider preserva el contrato de compatibilidad original; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicyy ClearImageDirectiveCell permiten que un ejecutor, generador, banda de rango o banda de tabla de Excel consuma directamente objetivos {{#image Key}} precompilados; si se omiten ambos proveedores, esas celdas de directiva quedan sin cambios

AutofitMode (type TXLSReportAutofitMode) selecciona un autoajuste de toda la hoja (xramNone, xramRows, xramColumnso xramBoth) aplicado una vez tras ejecutar todos los objetivos, y AutofitAdjustment es un factor adicional de margen (1.0 = ninguno, 1.1 = filas un 10 % más altas)

Ciclo de vida de generación y fuentes de plantilla

TXLSReportLifecyclePhase identifica los límites de lectura de plantilla, generación de libro y generación de hoja, mientras que TXLSReportLifecycleOutcome distingue devoluciones de llamada de entrada, completada, cancelada y fallida

TXLSReportLifecycleContext suministra el libro y la hoja de cálculo activos, identidad estable de la hoja, coordenadas originales y actuales, un IXLSReportDataViewde solo lectura, el número de objetivos y los detalles del primer fallo; cada evento previo de entrada recibe un evento posterior emparejado incluso cuando la generación se cancela o falla

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheet, and AfterGenerateSheet observan un conjunto congelado de hojas de cálculo originales; los cambios de estructura provocados por devoluciones de llamada activan una actualización de la compilación sin añadir a la ejecución actual las hojas recién creadas

TXLSReportGenerator acepta un libro, un nombre de archivo, un flujo propiedad del llamador o un archivo cifrado y añade BeforeReadTemplate y AfterReadTemplate a los eventos de generación; TXLSReportModificationMode selecciona mutación compatible in situ o generación por clonación atómica aislada. El SourceKind de solo lectura (de tipo TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStreamo xrtsEncryptedFile) y TemplateWorkbook informan de la fuente de plantilla configurada, mientras que ModificationMode e IncludeResolver se pueden configurar antes de una ejecución

File and stream templates usan xrmAtomicClonepor defecto; los flujos de entrada posicionables restauran su posición original, los flujos de solo avance se consumen en bloques acotados, los flujos del llamador permanecen abiertos y los flujos o archivos de salida se reemplazan solo tras una finalización exitosa

Planificación, comprobación y migración

TXLSReportPaginationPlanner proporciona planes KeepTogether, SplitRows, MergeSimilary BalanceColumns para pies de página fijos y salida equilibrada

TXLSReportTemplateChecker proporciona Check, CheckBandy CheckTableBand; TXLSReportTemplateMigrator proporciona MigrateText y MigrateWorkbook para las formas de marcador de posición heredadas compatibles

Ejemplo de 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;

Ejemplo de 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;

El FeatureShowcase de Delphi y el XlsxFeatureGallery de C++Builder contienen versiones ejecutables completas que verifican el estado de completado con errores y el recuento de problemas antes de liberar el ejecutor

Véase también

• Advanced workbook workflows
• TXLSXWorkbook
• TXLSPaginationModel