API de relatórios compilados

A unidade lxReport compila marcadores de posição e bandas de relatório estruturais uma vez e, em seguida, aplica dados pertencentes ao chamador através de cursores limitados, sem reexaminar os objetos gerados do livro de trabalho

Contratos de tabela e cursor

Fornecedores de consultas controlados

IXLSReportQueryExecutor.ExecuteReadOnly mantém a execução da consulta pertencente ao anfitrião e aceita apenas definições registadas pelo código da aplicação

TXLSReportQueryParameter, TXLSReportQueryParameters e TXLSReportQueryDefinition expõem Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameter e ClearParameters

TXLSReportQueryProvider utiliza RegisterQuery, RemoveQuery, Clear e TryGetTable, com Count, Definitions e MaximumTimeoutMS a expor a lista de permissões e o teto de tempo limite

Sessões de dados por execução

IXLSReportDataSession é a cache lazy isolada que suporta cada execução de relatório: DeclareRequest regista um TXLSReportDataRequest (do tipo TXLSReportDataRequestKind: xrdrkNamed ou xrdrkUser) cujo TXLSReportDataSource (do tipo TXLSReportDataSourceKind: não especificado, célula, banda de intervalo, banda de tabela ou expressão) e cuja lista de TXLSReportDataParameter descrevem a origem e os respetivos valores, e cujo RunControl é o handle de cancelamento IXLSReportRunControl do anfitrião; HasResolver testa uma chave de fornecedor, TryGetTable e RequireTable leem aliases em cache, TryResolveTable e RequireResolvedTable resolvem sob demanda para um TXLSReportDataResolveResult (com estado TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFound ou xrdrsDataError), e TryGetState reporta um TXLSReportDataSessionState de a carregar, resolvido, não encontrado ou erro de dados, enquanto CachedAliasCount e ResolvedAliasCount expõem o tamanho da sessão

IXLSReportDataView.TryGetValue procura um valor nomeado sem gerar exceção, complementando os acessores indexados Count, Names e Values

Relações e combinadores de tabelas preguiçosas

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

TXLSReportAggregateKind, TXLSReportAggregate e TXLSReportJoinKind configuram TXLSReportTableFactory

Bandas de intervalo nomeadas e explícitas

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

TXLSCompiledReportBand aceita um nome definido de âmbito exato ou CreateForRange e, em seguida, expande-se através das sobrecargas de Run; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCount e State expõem o plano compilado

TXLSCompiledTableReportBand.Run expande uma linha de modelo de dados de tabela do Excel preservando os metadados da tabela; inspecione TableName, Sheet, SheetIndex, ExcelTable, TemplateRow e State

TXLSCompiledSheetReportBand.Run cria folhas por registo utilizando NameColumn, NamePrefix e DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run cria folhas de continuação utilizando NamePrefix e DeleteTemplateAfterRun

Modelos de livro de trabalho completo

TXLSReportTemplateTarget e TXLSReportTemplateTargets selecionam células, comentários, hiperligações, formas, cabeçalhos e rodapés, nomes de folhas, nomes definidos e propriedades do documento

TXLSCompiledReportTemplate.Compile captura destinos e expressões, Analyze devolve TXLSReportIssues endereçadas, as sobrecargas de Run aplicam valores e WriteDiagnostics escreve os problemas numa folha de cálculo; TargetAreas e TargetCount descrevem a superfície compilada

TXLSReportIssueKind, TXLSReportIssue e TXLSReportIssues identificam conteúdo de marcador de posição malformado, em falta, 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 o seu sinalizador Immutable permite a reutilização segura; TXLSReportIncludeLibrary fornece Add, Remove, Clear, Freeze, Resolve, Count e Immutable

IXLSReportImageProvider.TryGetImage devolve um TXLSReportImageValue configurado por TXLSReportImageFit; TXLSReportMissingImagePolicy controla os recursos em falta, enquanto TXLSReportImageBinder.Apply, MissingPolicy e ClearDirectiveCell atualizam diretivas de imagem exatas

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, TXLSReportRunProgress e TXLSReportRunProgressEvent descrevem os limites de progresso e cancelamento

TXLSCompiledReportRunner expõe Run, RunToStream, RunToFile e Cancel, com ReportTemplate, State, Progress, OnProgress e OnFormat a controlar a execução reutilizável; a validação falhada levanta EXLSReportData antes de gravações determinísticas

Ciclo de vida de geração e origens de modelos

TXLSReportLifecyclePhase identifica os limites de leitura do modelo, de geração do livro e de geração da folha de cálculo, enquanto TXLSReportLifecycleOutcome distingue callbacks de entrada, concluídas, canceladas e falhadas

TXLSReportLifecycleContext fornece o livro e a folha de cálculo ativos, identidade estável da folha de cálculo, coordenadas originais e atuais, uma IXLSReportDataView só de leitura, a contagem de destinos e os detalhes da primeira falha; cada evento de entrada recebe um evento final emparelhado, mesmo que a geração seja cancelada ou falhe

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheet e AfterGenerateSheet observam um conjunto congelado de folhas de cálculo originais; alterações de estrutura conduzidas por callbacks acionam uma atualização da compilação sem adicionar folhas recém-criadas à execução em curso

TXLSReportGenerator aceita um livro, um nome de ficheiro, um stream pertencente ao chamador ou um ficheiro encriptado e adiciona BeforeReadTemplate e AfterReadTemplate aos eventos de geração; TXLSReportModificationMode seleciona mutação compatível no local ou geração por clone atómico isolado. O SourceKind só de leitura (do tipo TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStream ou xrtsEncryptedFile) e o TemplateWorkbook reportam a origem do modelo configurada, enquanto ModificationMode e IncludeResolver podem ser definidos antes de uma execução

Os modelos de ficheiro e de stream assumem xrmAtomicClone por predefinição; streams de entrada com posição recuperável repõem a posição original, streams apenas de avanço são consumidos em blocos limitados, os streams do chamador mantêm-se abertos, e os streams ou ficheiros de saída só são substituídos após conclusão com sucesso

Planeamento, verificação e migração

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

TXLSReportTemplateChecker fornece Check, CheckBand e CheckTableBand; TXLSReportTemplateMigrator fornece MigrateText e MigrateWorkbook para formas de marcador de posição legadas suportadas

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;

A FeatureShowcase de Delphi e a XlsxFeatureGallery de C++Builder contêm versões completas executáveis que verificam o estado de concluído-com-erros e o número de problemas antes de libertar o runner

Veja também

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