API de relatórios compilados

A unidade lxReport compila os espaços reservados e as faixas estruturais de relatório uma vez e, em seguida, aplica os dados de propriedade do chamador por meio de cursores limitados, sem reexaminar os objetos de pasta de trabalho gerados

Contratos de tabela e cursor

Provedores de consulta controlados

IXLSReportQueryExecutor.ExecuteReadOnly mantém a execução de consultas sob propriedade do host e aceita somente definições registradas pelo código do aplicativo

TXLSReportQueryParameter, TXLSReportQueryParameterse TXLSReportQueryDefinition expõem Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParametere ClearParameters

TXLSReportQueryProvider usa RegisterQuery, RemoveQuery, Cleare TryGetTable, com Count, Definitionse MaximumTimeoutMS expondo a lista de permissões e o teto de tempo limite

Sessões de dados por execução

IXLSReportDataSession é o cache lazy isolado por trás de uma execução de relatório: DeclareRequest registra um TXLSReportDataRequest (tipo TXLSReportDataRequestKind: xrdrkNamed ou xrdrkUser) cujo TXLSReportDataSource (tipo TXLSReportDataSourceKind: não especificado, célula, faixa de intervalo, faixa de tabela ou expressão) e lista de TXLSReportDataParameter descrevem a origem e seus valores, e cujo RunControl é o handle de cancelamento IXLSReportRunControl do host; HasResolver testa uma chave de provider, TryGetTable e RequireTable leem aliases em cache, TryResolveTable e RequireResolvedTable resolvem sob demanda em um TXLSReportDataResolveResult (status TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFoundou xrdrsDataError), e TryGetState informa um TXLSReportDataSessionState de carregando, resolvido, não encontrado ou erro de dados, enquanto CachedAliasCount e ResolvedAliasCount expõem o tamanho da sessão

IXLSReportDataView.TryGetValue busca um valor nomeado sem lançar exceção, complementando os acessadores indexados Count, Namese Values accessors

Relações e combinadores de tabela lenta

TXLSReportRowIndexes e TXLSReportRelationIndex retêm números de linhas filhas em baldes de chave composta; use FindChildRows ou CreateChildCursor e inspecione BucketCount ou IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregatee TXLSReportJoinKind configuram TXLSReportTableFactory, whose row filters compare through TXLSReportFilterOperator (xrfoEqual, xrfoNotEqual, xrfoGreater, xrfoGreaterEqual, xrfoLess, xrfoLessEqual, xrfoContains, xrfoStartsWith, xrfoEndsWith)

Faixas nomeadas e de intervalo explícito

TXLSReportBandKind seleciona expansão de linha, coluna ou tabela cruzada, e TXLSReportBandState informa o estado do ciclo de vida

TXLSCompiledReportBand aceita um nome definido de escopo exato ou CreateForRangee, em seguida, expande por meio das sobrecargas de Run ; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCounte State expõem o plano compilado

EmptyBandPolicy expande uma linha de modelo de dados de tabela do Excel preservando os metadados da tabela; inspecione TXLSEmptyBandPolicy, xreKeepTemplate , xreClearTemplate , xreDeleteTemplate , DeleteLastRow e BandHeight linhas do bloco expandido depois que suas cópias pousam, de modo que as linhas separadoras de X-range restantes colapsem

FixedBand faz com que as faixas de linha sobrescrevam as linhas abaixo do modelo em vez de inserir novas, o que mantém o conteúdo ao redor em posição fixa

Faixas de intervalo de linhas e colunas clonam conversas de comentários encadeados quando toda raiz e toda resposta pertencem ao intervalo do template; placeholders de texto e de nome de exibição são avaliados para cada registro, os comentários copiados recebem novos identificadores e identificadores pai remapeados, e os registros de pessoas existentes da pasta de trabalho são reutilizados

A compilação rejeita conversas divididas no limite do template, pais ausentes, identificadores duplicados e âncoras de célula inválidas antes da expansão; o estouro de âncora é verificado antes da mutação da planilha, e uma execução com falha ou cancelada remove as conversas geradas enquanto restaura o estado do template

TXLSCompiledTableReportBand.Run expande uma linha de data-template de tabela do Excel preservando os metadados da tabela; inspecione TableName, Sheet, SheetIndex, ExcelTable, TemplateRow, and State, e configure as mesmas propriedades de imagem V2 expostas pelas range bands

Range and Excel-table bands share ErrorMode, StrictDataAccess, RuntimeLimits, and immutable LastResult snapshots; xremWriteAndContinue escreve apenas falhas de célula explicitamente recuperáveis como diagnósticos literais, registra a BandInputRow e as coordenadas reais de saída, e continua com os alvos e linhas seguintes, enquanto falhas estruturais, de cancelamento, de limite de recursos, de callback e de rollback permanecem fatais

TXLSCompiledSheetReportBand.Run cria planilhas por registro usando NameColumn, NamePrefixe DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run cria planilhas de continuação usando NamePrefix e DeleteTemplateAfterRun

Modelos de pasta de trabalho inteira

TXLSReportTemplateTarget e TXLSReportTemplateTargets selecionam células, comentários, hiperlinks, formas, cabeçalhos e rodapés, nomes de planilhas, nomes definidos e propriedades do documento

TXLSCompiledReportTemplate.Compile captures targets and expressions, Analyze returns addressed TXLSReportIssues, the Run overloads apply values, and WriteDiagnostics writes issues to a worksheet; TargetAreas, TargetCount, and UserTableCount descrevem a superfície compilada e as tabelas de usuário registradas

ProcessStructuralDirectives (default True) makes a template Run captura destinos e expressões, {{#delete}} retorna {{#format}} endereçados, as sobrecargas de TXLSReportDirectiveProcessor aplicam valores e AppliedCount grava os problemas em uma planilha; CreateEncrypted e Workbook descrevem a superfície compilada

TXLSReportIssueKind, TXLSReportIssuee TXLSReportIssues identificam conteúdo de espaço reservado malformado, ausente, inválido, desconhecido ou cíclico com coordenadas de destino e de célula

Inclusões, imagens e formatação

IXLSReportIncludeResolver.Resolve fornece fragmentos nomeados e seu sinalizador Immutable permite reutilização segura; TXLSReportIncludeLibrary fornece Add, Remove, Clear, Freeze, Resolve, Counte Immutable

IXLSReportImageProvider.TryGetImage retorna um TXLSReportImageValue configurado por TXLSReportImageFit; TXLSReportMissingImagePolicy controla recursos ausentes, enquanto TXLSReportImageBinder.Apply, ApplyTargete MissingPolicyatualizam diretivas de imagem exatas ClearDirectiveCell update exact image directives

TXLSReportImageBinder.ApplyTargetV2 vincula uma célula de diretiva através do contrato de provider V2 e repassa um TXLSReportTransformImageEvent que pode reescrever o payload resolvido antes de ele chegar ao destino; o placeholder resolvido em si é um TXLSReportEvaluatedTarget whose TXLSReportEvaluatedTargetKind distinguishes xretNone, xretText, xretValue, and xretFormula; IXLSReportImageCancellation.IsCancellationRequested permite que providers de execução longa observem um cancelamento cooperativo

IXLSReportImageDataProviderV2.GetImage receives TXLSReportImageRequest com identidade estável de planilha, alvo compilado, nomes de band e de tabela, linhas lógicas e de cursor, uma visão somente leitura da linha atual, células de diretiva e de âncora, dimensões do alvo e offsets em EMU, e IXLSReportImageCancellation

TXLSReportImageResult carries a TXLSReportImagePayload whose Kind (TXLSReportImagePayloadKind) selects xripMissing, bytes ou um fluxo, com o tempo de vida do fluxo declarado por TXLSReportImageStreamOwnership: xrisoBorrowed permanecem sob posse do chamador e restauram sua posição quando seekable, enquanto xrisoTransferred são liberados exatamente uma vez; opcional SourceWidth, SourceHeight, SourceDpiX, and SourceDpiY afirmam ou sobrescrevem a geometria física da origem

xrifNatural uses the source physical size, xrifContain ajusta a escala e centraliza dentro da caixa alvo, xrifCover preenche a caixa com recorte simétrico da origem, e xrifStretch preenche sem preservar a proporção; a geometria de PNG, JPEG, GIF, BMP, EMF e WMF é lida de cabeçalhos limitados sem decodificar pixels

OnTransformImage roda depois que os dados do provider são capturados em snapshot e antes da mutação da planilha; MaximumImageBytes tem 64 MiB como padrão, e assinaturas de payload, cabeçalhos de geometria, pares de dimensão e DPI, limites de lado raster e de pixels, âncoras e coordenadas de grade são validados antes do binding

TXLSXImage.OffsetXEMU and OffsetYEMU retêm a posição da imagem dentro da célula ou da âncora absoluta através de round trips XLSX e ODS

TXLSReportDynamicFormat e TXLSReportFormatEvent permitem que um executor aplique formatos de número, alturas de linha e larguras de coluna por destino

Execução reutilizável

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgresse TXLSReportRunProgressEvent descrevem progresso e limites de cancelamento

TXLSCompiledReportRunner expõe Run, RunToStream, RunToFilee RunToEncryptedFile, and Cancel, with ReportTemplate, State, Progress, OnProgress, and OnFormat controlando a execução reutilizável; validação com falha dispara EXLSReportData before deterministic writes

ErrorMode (type TXLSReportErrorMode) defaults to xremStop; xremWriteAndContinue handles only explicit EXLSReportRecoverableData failures and resolver DataError resultados, registra problemas imutáveis ordenados em LastResult (an IXLSReportRunResult exposing State, AppliedCount, IssueCount, indexed Issues, and the FailureClassName / FailureMessage of a fatal failure) whose TXLSReportRuntimeIssue snapshots expose their Category (a TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProvider, or xrricExpression) and report TargetIndex, SheetName, Col, and whether the issue was already WasWritten into the output, and finishes as xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults permite 100.000 problemas retidos, 512 caracteres por mensagem sanitizada e 16 MiB de memória para problemas; atribua um RuntimeLimits record before a run, and leave RuntimeDiagnosticsSheetName vazio, a menos que uma planilha de diagnósticos estruturados seja necessária

Valores e fórmulas de célula recuperáveis viram [Report error CODE] message texto literal, alvos seguros fora de células mantêm o valor original, e uma planilha de diagnósticos opcional marca esses problemas estruturados como gravados; falhas de nome de planilha e de fórmula de nome definido sempre interrompem, porque podem alterar a estrutura da pasta de trabalho

Erros de dados declarados pelo resolver, divisão por zero em expressões e expressões regulares inválidas usam categorias estáveis de provider ou de expressão; exceções lançadas pelo resolver e todas as falhas de callback, cancelamento, limite de recursos, rollback, serialização, segurança e estruturais permanecem fatais

RunToStream, RunToFile, and RunToEncryptedFile concentram a serialização em estágios dentro do mesmo tempo de vida de execução e de sessão de dados e publicam uma única vez; qualquer falha fatal, cancelada, de serialização, de gravação parcial no fluxo ou de substituição do destino preserva o destino anterior completo e libera o armazenamento temporário antes de retornar

Um fluxo de saída não vazio precisa ser legível, gravável, redimensionável e seekable, para que o rollback possa restaurar seus bytes, tamanho e posição originais; snapshots de até 8 MiB permanecem em memória e snapshots maiores usam armazenamento temporário gerenciado, enquanto um commit bem-sucedido deixa o fluxo posicionado em zero

A saída não criptografada usa o formato de origem da pasta de trabalho gerada, de modo que um template ODS produz um fluxo ou arquivo ODS com os metadados de pacote exigidos; a saída criptografada continua usando o contêiner Office criptografado

ImageProvider preserva o contrato de compatibilidade original; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicy, and ClearImageDirectiveCell permitem que um runner, um generator, uma range band ou uma banda de tabela do Excel consumam {{#image Key}} alvos pré-compilados diretamente; omitir ambos os providers deixa essas células de diretiva inalteradas

AutofitMode , com TXLSReportAutofitMode,xramNone, xramRows, xramColumnse xramBothcontrolando a execução reutilizável; falha na validação gera AutofitAdjustment antes de gravações determinísticas

Ciclo de vida de geração e fontes de modelo

TXLSReportLifecyclePhase identifica os limites de leitura do modelo, de geração da pasta de trabalho e de geração da planilha, enquanto TXLSReportLifecycleOutcome distingue callbacks iniciados, concluídos, cancelados e com falha

TXLSReportLifecycleContext fornece a pasta de trabalho e a planilha ativas, identidade estável da planilha, coordenadas originais e atuais, um IXLSReportDataViewsomente leitura, quantidade de destinos e detalhes da primeira falha; todo evento de antes iniciado recebe um evento de depois em par, mesmo quando a geração é cancelada ou falha

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheete AfterGenerateSheet observam um conjunto congelado de planilhas originais; mudanças de estrutura orientadas por callback disparam atualização da compilação sem adicionar planilhas recém-criadas à execução atual

TXLSReportGenerator aceita uma pasta de trabalho, nome de arquivo, stream de propriedade do chamador ou arquivo criptografado, e adiciona BeforeReadTemplate e AfterReadTemplate aos eventos de geração; TXLSReportModificationMode seleciona mutação in-place compatível ou geração por clone atômico isolado. SourceKind somente leitura (tipo TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStreamou xrtsEncryptedFile) e TemplateWorkbook informam a fonte de modelo configurada, enquanto ModificationMode e IncludeResolver podem ser definidos antes de uma execução

Modelos de arquivo e stream têm padrão xrmAtomicClone; streams de entrada com seek restauram sua posição original, streams forward-only são consumidos em blocos limitados, streams do chamador permanecem abertos, e streams ou arquivos de saída só são substituídos após conclusão com sucesso

Planejamento, verificação e migração

TXLSReportPaginationPlanner fornece planos KeepTogether, SplitRows, MergeSimilare BalanceColumns para rodapés fixos e saída balanceada

TXLSReportTemplateChecker fornece Check, CheckBande CheckTableBand; TXLSReportTemplateMigrator fornece MigrateText e MigrateWorkbook para formas legadas suportadas de espaços reservados

Exemplo em 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;

Exemplo em 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;

O FeatureShowcase do Delphi e o XlsxFeatureGallery do C++Builder contêm versões completas e executáveis que verificam o estado concluído com erros e a quantidade de ocorrências antes de liberar o runner

Veja também

• Fluxos de trabalho avançados de pasta de trabalho
• TXLSXWorkbook
• TXLSPaginationModel