API de informes compilados

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

Contratos de tablas y cursores

Proveedores de consultas controlados

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

TXLSReportQueryParameter, TXLSReportQueryParametersy TXLSReportQueryDefinition exponen Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParametery ClearParameters

TXLSReportQueryProvider usa RegisterQuery, RemoveQuery, Cleary TryGetTable, con Count, Definitionsy MaximumTimeoutMS exponiendo la lista blanca y el límite 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 (tipo TXLSReportDataRequestKind: xrdrkNamed o xrdrkUser) cuyo TXLSReportDataSource (tipo TXLSReportDataSourceKind: sin especificar, celda, banda de rango, banda de tabla o expresión) y lista de TXLSReportDataParameter describen el origen 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 en caché, TryResolveTable y RequireResolvedTable resuelven a demanda en un TXLSReportDataResolveResult (estado TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFoundo xrdrsDataError), y TryGetState informa 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 y TXLSReportRelationIndex conservan números de filas secundarias en depósitos de clave compuesta; use FindChildRows o CreateChildCursor e inspeccione BucketCount o IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregatey TXLSReportJoinKind configuran TXLSReportTableFactory, cuyos filtros de filas 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 de filas, columnas o tabulación cruzada, y TXLSReportBandState informa del estado del ciclo de vida: lista, en ejecución, completada, completada con errores, cancelada o fallida

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

EmptyBandPolicy (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 limpia las celdas de la banda incluidos los marcadores de posición, y xreDeleteTemplate elimina las filas de la plantilla — y DeleteLastRow quita las últimas BandHeight filas del bloque expandido después de que aterricen sus copias, para que las filas separadoras de rango X finales se colapsen

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

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

La compilación rechaza las conversaciones divididas a través del límite de la plantilla, los padres faltantes, los identificadores duplicados y los anclajes de celda inválidos antes de la expansión; el desborde de anclajes se comprueba antes de mutar la hoja, 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 expuestas por 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 explícitos y recuperables de celdas, registra la BandInputRow de origen y las coordenadas reales de salida, y continúa con los destinos y filas posteriores, mientras que los fallos estructurales, de cancelación, de límite de recursos, de callbacks y de rollback siguen siendo fatales

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

Plantillas de todo el libro

TXLSReportTemplateTarget y 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 destinos y expresiones, Analyze devuelve TXLSReportIssuesdireccionados, 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 ( Truede forma predeterminada) hace que un Run de plantilla ejecute las directivas estructurales {{#delete}} y {{#format}} después de aplicar los destinos de valor — el TXLSReportDirectiveProcessor que hay detrás analiza los rangos, los aplica e informa cuántos manejó mediante AppliedCount — y CreateEncrypted abre una plantilla cifrada con su contraseña y la compila manteniendo el libro de trabajo accesible a través de la propiedad Workbook property

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

Inclusiones, imágenes y formato

IXLSReportIncludeResolver.Resolve suministra fragmentos con nombre y su marca 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 faltantes, mientras TXLSReportImageBinder.Apply, ApplyTarget, MissingPolicyy ClearDirectiveCell actualizan directivas de imagen exactas

TXLSReportImageBinder.ApplyTargetV2 vincula una celda de directiva a través del contrato de proveedor V2 y reenvía un TXLSReportTransformImageEvent que puede reescribir la carga útil resuelta antes de que aterrice; el marcador de posición resuelto en sí 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, destino compilado, nombres de banda y de tabla, filas lógicas y de cursor, una vista de solo lectura de la fila actual, celdas de directiva y de ancla, dimensiones y desfases del destino en EMU, e IXLSReportImageCancellation

TXLSReportImageResult transporta un TXLSReportImagePayload cuyo Kind (TXLSReportImagePayloadKind) selecciona xripMissing, bytes o un flujo, con el tiempo 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 SourceWidth, SourceHeight, SourceDpiXy SourceDpiY opcionales afirman o anulan 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 PNG, JPEG, GIF, BMP, EMF y WMF se lee de encabezados acotados sin decodificar 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 como valor predeterminado 64 MiB, y las firmas de cargas útiles, los encabezados de geometría, los pares de dimensión y DPI, los límites de lado y píxeles raster, las anclas y las coordenadas de cuadrícula se validan antes del enlace

TXLSXImage.OffsetXEMU y OffsetYEMU conservan la posición de una imagen dentro de su celda o ancla absoluta a través de los round-trip de XLSX y ODS

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

Ejecución reutilizable

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgressy TXLSReportRunProgressEvent describen el progreso y los límites de cancelación

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

ErrorMode (tipo TXLSReportErrorMode) es xremStopde forma predeterminada; xremWriteAndContinue maneja solo los fallos explícitos EXLSReportRecoverableData y los resultados DataError de resolvedores, 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 TargetIndex, SheetName, Coly si el problema ya se había WasWritten en la salida, y termina como xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults permite 100 000 problemas retenidos, 512 caracteres por mensaje depurado 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 necesite una hoja de diagnósticos estructurada

Los valores y fórmulas de celda recuperables se convierten en texto literal [Report error CODE] message , los destinos seguros que no son de celda conservan su valor original, y una hoja de diagnósticos opcional marca esos problemas estructurados como escritos; los fallos de nombres de hoja y de fórmulas de nombres definidos siempre detienen la ejecución porque pueden cambiar la estructura del libro de trabajo

Los errores de datos declarados por resolvedores, 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 resolvedores y todos los fallos de callbacks, cancelación, límite de recursos, rollback, serialización, seguridad y estructura siguen siendo fatales

RunToStream, RunToFiley RunToEncryptedFile dejan la serialización en preparación dentro del mismo tiempo de vida de ejecución y sesión de datos, y 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 el rollback 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 de trabajo 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 los destinos precompilados {{#image Key}} ; si se omiten ambos proveedores, esas celdas de directiva quedan sin cambios

AutofitMode (tipo TXLSReportAutofitMode) selecciona un autofit de toda la hoja (xramNone, xramRows, xramColumnso xramBoth) aplicado una vez después de que todos los destinos se ejecuten, y AutofitAdjustment es un factor adicional de margen (1.0 = ninguno, 1.1 = filas 10% más altas)

Ciclo de vida de generación y orígenes de plantillas

TXLSReportLifecyclePhase identifica los límites de lectura de plantilla, generación del libro de trabajo y generación de hojas de cálculo, mientras que TXLSReportLifecycleOutcome distingue los callbacks entrados, completados, cancelados y fallidos

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

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheety AfterGenerateSheet observan un conjunto congelado de hojas de cálculo originales; los cambios de estructura impulsados por callbacks disparan una actualización de compilación sin agregar las hojas recién creadas a la ejecución actual

TXLSReportGenerator acepta un libro de trabajo, un nombre de archivo, un flujo propiedad del llamador o un archivo cifrado, y agrega BeforeReadTemplate y AfterReadTemplate a los eventos de generación; TXLSReportModificationMode selecciona mutación en el sitio compatible o generación por clonación atómica aislada. El SourceKind de solo lectura (tipo TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStreamo xrtsEncryptedFile) y TemplateWorkbook informan el origen de plantilla configurado, mientras que ModificationMode e IncludeResolver se pueden ajustar antes de una ejecución

Las plantillas de archivo y de flujo usan xrmAtomicClonede forma predeterminada; 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 formas de marcador de posición heredadas admitidas

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;

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

Véase también

• Flujos de trabajo avanzados de libros
• TXLSXWorkbook
• TXLSPaginationModel