API kompilovaného sestavování

Jednotka lxReport kompiluje zástupné znaky a strukturální pásy sestav jednou a poté aplikuje data vlastněná volajícím prostřednictvím ohraničených kurzorů bez opětovného prohledávání generovaných objektů sešitu

Kontrakty tabulek a kurzorů

Řízené poskytovatele dotazů

IXLSReportQueryExecutor.ExecuteReadOnly ponechává provádění dotazů v rukou hostitele a přijímá pouze definice registrované kódem aplikace

TXLSReportQueryParameter, TXLSReportQueryParameters a TXLSReportQueryDefinition zpřístupňují Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameter a ClearParameters

TXLSReportQueryProvider používá RegisterQuery, RemoveQuery, Clear a TryGetTable, přičemž Count, Definitions a MaximumTimeoutMS zpřístupňují bílou listinu a strop časového limitu

Relace dat jednotlivých běhů

IXLSReportDataSession je izolovaná odložená mezipaměť za jedním během sestavy: DeclareRequest registruje TXLSReportDataRequest (druh TXLSReportDataRequestKind: xrdrkNamed nebo xrdrkUser), jehož TXLSReportDataSource (druh TXLSReportDataSourceKind: nespecifikováno, buňka, pás rozsahu, pás tabulky nebo výraz) a seznam TXLSReportDataParameter popisují zdroj a jeho hodnoty a jehož RunControl je obslužný IXLSReportRunControl pro zrušení; HasResolver otestuje klíč poskytovatele, TryGetTable a RequireTable čtou aliasy z mezipaměti, TryResolveTable a RequireResolvedTable na požádání vyřeší do TXLSReportDataResolveResult (stav TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFound nebo xrdrsDataError) a TryGetState hlásí TXLSReportDataSessionState načítání, vyřešeno, nenalezeno nebo chyba dat, přičemž CachedAliasCount a ResolvedAliasCount zpřístupňují velikost relace

IXLSReportDataView.TryGetValue vyhledá jednu pojmenovanou hodnotu bez vyvolání výjimky a doplňuje indexovaný přístup přes Count, Names a Values

Relace a kombinátory odložených tabulek

TXLSReportRowIndexes a TXLSReportRelationIndex uchovávají čísla podřízených řádků v segmentech složených klíčů; použijte FindChildRows nebo CreateChildCursor a prohlédněte si BucketCount nebo IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregate a TXLSReportJoinKind konfigurují TXLSReportTableFactory, jejíž řádkové filtry porovnávají přes TXLSReportFilterOperator (xrfoEqual, xrfoNotEqual, xrfoGreater, xrfoGreaterEqual, xrfoLess, xrfoLessEqual, xrfoContains, xrfoStartsWith, xrfoEndsWith)

Pojmenované a explicitní pásy rozsahů

TXLSReportBandKind vybírá rozšíření po řádcích, sloupcích nebo v kontingenční tabulce a TXLSReportBandState hlásí stav životního cyklu: připraveno, běží, dokončeno, dokončeno s chybami, zrušeno nebo selhalo

TXLSCompiledReportBand přijímá definovaný název s přesným rozsahem nebo CreateForRange a poté se rozšiřuje prostřednictvím přetížení Run; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCount a State zpřístupňují kompilovaný plán

EmptyBandPolicy (typ TXLSEmptyBandPolicy) řídí, co pás udělá s řádky své šablony, když je datová sada prázdná — xreKeepTemplate nechá řádky nedotčené, xreClearTemplate vymaže buňky pásu včetně zástupných znaků a xreDeleteTemplate řádky šablony smaže — a DeleteLastRow odstraní závěrečných BandHeight řádků rozbaleného bloku poté, co se jeho kopie uloží, takže koncové oddělovací řádky X-range se sbalí

FixedBand způsobí, že řádkové pásy přepíšou řádky pod šablonou místo vkládání nových, takže okolní obsah zůstane na pevné pozici

TXLSCompiledTableReportBand.Run rozšiřuje jeden datový řádek šablony excelové tabulky při zachování metadat tabulky; prohlédněte si TableName, Sheet, SheetIndex, ExcelTable, TemplateRow a State a nakonfigurujte stejné vlastnosti obrázků V2, které zpřístupňují pásy rozsahů

Pásy rozsahů a excelových tabulek sdílejí ErrorMode, StrictDataAccess, RuntimeLimits a neměnné snímky LastResult; xremWriteAndContinue zapisuje jako doslovnou diagnostiku pouze explicitní obnovitelné chyby buněk, zaznamenává zdrojový BandInputRow a skutečné výstupní souřadnice a pokračuje v dalších cílech a řádcích, zatímco strukturální chyby, zrušení, limity prostředků, zpětná volání a rollback zůstávají fatální

TXLSCompiledSheetReportBand.Run vytváří listy pro jednotlivé záznamy pomocí NameColumn, NamePrefix a DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run vytváří pokračovací listy pomocí NamePrefix a DeleteTemplateAfterRun

Šablony celého sešitu

TXLSReportTemplateTarget a TXLSReportTemplateTargets vybírají buňky, komentáře, hypertextové odkazy, tvary, záhlaví a zápatí, názvy listů, definované názvy a vlastnosti dokumentu

TXLSCompiledReportTemplate.Compile zachytává cíle a výrazy, Analyze vrací adresované TXLSReportIssues, přetížení Run aplikují hodnoty a WriteDiagnostics zapisuje problémy na list; TargetAreas, TargetCount a UserTableCount popisují kompilovaný povrch a registrované uživatelské tabulky

ProcessStructuralDirectives (výchozí True) zajistí, že Run šablony po aplikaci hodnotových cílů provede strukturální direktivy {{#delete}} a {{#format}} — TXLSReportDirectiveProcessor v pozadí rozparsuje rozsahy, aplikuje je a přes AppliedCount ohlásí, kolik jich zpracoval — a CreateEncrypted otevře zašifrovanou šablonu s heslem a zkompiluje ji, přičemž sešit zůstane dostupný přes vlastnost Workbook

TXLSReportIssueKind, TXLSReportIssue a TXLSReportIssues identifikují chybný, chybějící, neplatný, neznámý nebo cyklický obsah zástupných znaků se souřadnicemi cíle a buněk

Vložení, obrázky a formátování

IXLSReportIncludeResolver.Resolve dodává pojmenované fragmenty a jeho příznak Immutable umožňuje bezpečné opakované použití; TXLSReportIncludeLibrary poskytuje Add, Remove, Clear, Freeze, Resolve, Count a Immutable

IXLSReportImageProvider.TryGetImage vrací TXLSReportImageValue konfigurovaný pomocí TXLSReportImageFit; TXLSReportMissingImagePolicy řídí chybějící prostředky, zatímco TXLSReportImageBinder.Apply, ApplyTarget, MissingPolicy a ClearDirectiveCell aktualizují přesné direktivy obrázků

TXLSReportImageBinder.ApplyTargetV2 sváže jednu direktivní buňku přes smlouvu poskytovatele V2 a přeposlá TXLSReportTransformImageEvent, který může vyřešený obsah přepsat ještě před zápisem; samotný vyřešený zástupný znak je TXLSReportEvaluatedTarget, jehož TXLSReportEvaluatedTargetKind rozlišuje xretNone, xretText, xretValue a xretFormula; IXLSReportImageCancellation.IsCancellationRequested umožňuje dlouho běžícím poskytovatelům vnímat kooperativní zrušení

IXLSReportImageDataProviderV2.GetImage přijímá TXLSReportImageRequest se stabilní identitou listu, zkompilovaným cílem, názvy pásu a tabulky, logickými a kurzorovými řádky, pohledem jen pro čtení na aktuální řádek, direktivní a kotvící buňkou, rozměry cíle a posuny v EMU a IXLSReportImageCancellation

TXLSReportImageResult nese TXLSReportImagePayload, jejíž Kind (TXLSReportImagePayloadKind) volí xripMissing, bajty nebo stream, přičemž životnost streamu deklaruje TXLSReportImageStreamOwnership: streamy xrisoBorrowed zůstávají vlastnictvím volajícího a při podpoře seek obnoví svou pozici, zatímco streamy xrisoTransferred se uvolňují právě jednou; volitelné SourceWidth, SourceHeight, SourceDpiX a SourceDpiY potvrzují nebo přepisují fyzickou geometrii zdroje

xrifNatural použije fyzickou velikost zdroje, xrifContain škáluje a vycentruje do cílového rámu, xrifCover zaplní rám se symetrickým ořezem zdroje a xrifStretch jej zaplní bez zachování poměru stran; geometrie PNG, JPEG, GIF, BMP, EMF a WMF se čte z ohraničených hlaviček bez dekódování pixelů

OnTransformImage běží po pořízení snímku dat poskytovatele a před zápisem do listu; MaximumImageBytes má výchozích 64 MiB a podpisy obsahu, geometrické hlavičky, dvojice rozměrů a DPI, limity raster stran a pixelů, kotvy i mřížné souřadnice se před svázáním validují

TXLSXImage.OffsetXEMU a OffsetYEMU zachovávají pozici obrázku uvnitř buňky nebo absolutní kotvy při roundtrip XLSX i ODS

TXLSReportDynamicFormat a TXLSReportFormatEvent umožňují spouštěči aplikovat formáty čísel, výšky řádků a šířky sloupců pro každý cíl

Znovupoužitelné provádění

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgress a TXLSReportRunProgressEvent popisují hranice průběhu a zrušení

TXLSCompiledReportRunner zpřístupňuje Run, RunToStream, RunToFile, RunToEncryptedFile a Cancel, přičemž ReportTemplate, State, Progress, OnProgress a OnFormat řídí znovupoužitelné provádění; neúspěšná validace vyvolá EXLSReportData před deterministickými zápisy

ErrorMode (typ TXLSReportErrorMode) má výchozí hodnotu xremStop; xremWriteAndContinue zpracuje pouze explicitní selhání EXLSReportRecoverableData a výsledky DataError rezolverů, zaznamená uspořádané neměnné problémy do LastResult (rozhraní IXLSReportRunResult se State, AppliedCount, IssueCount, indexovanými Issues a FailureClassName / FailureMessage fatálního selhání), jejíž snímky TXLSReportRuntimeIssue zpřístupňují Category (typ TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProvider nebo xrricExpression) a hlásí TargetIndex, SheetName, Col a zda byl problém už WasWritten do výstupu, a běh pak skončí jako xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults povoluje 100 000 uchovaných problémů, 512 znaků na sanitizovanou zprávu a 16 MiB paměti na problémy; před během přiřaďte kladný vlastní záznam RuntimeLimits a RuntimeDiagnosticsSheetName nechte prázdné, pokud nepotřebujete jeden strukturovaný diagnostický list

Obnovitelné hodnoty a vzorce buněk se zapíší jako doslovný text [Report error CODE] message, bezpečné necílové buňky si ponechají původní hodnotu a volitelný diagnostický list tyto strukturované problémy označí jako zapsané; chyby názvů listů a vzorců definovaných názvů vždy zastaví běh, protože mohou změnit strukturu sešitu

Datové chyby deklarované rezolverem, dělení nulou ve výrazu a neplatné regulární výrazy používají stabilní kategorie poskytovatele nebo výrazu; vyvolané výjimky rezolverů a všechna selhání zpětných volání, zrušení, limitů prostředků, rollbacku, serializace, zabezpečení i strukturální selhání zůstávají fatální

RunToStream, RunToFile a RunToEncryptedFile připraví serializaci v rámci životnosti téhož běhu a datové relace a publikují jednou; jakékoliv fatální selhání, zrušení, chyba serializace, částečný zápis do streamu nebo nahrazení cíle zachová kompletní předchozí cíl a před návratem uvolní dočasné úložiště

Neprázdný výstupní stream musí být čitelný, zapisovatelný, zvětšitelný a seekovatelný, aby rollback mohl obnovit původní bajty, velikost i pozici; snímky do 8 MiB zůstávají v paměti, větší používají spravované dočasné úložiště a po úspěšném commitu je stream nastaven na nulu

Nešifrovaný výstup použije formát zdroje generovaného sešitu, takže šablona ODS vyprodukuje ODS stream nebo soubor s vyžadovanými metadaty balíčku; šifrovaný výstup nadále používá zašifrovaný kontejner Office

ImageProvider zachovává původní smlouvu o kompatibilitě; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicy a ClearImageDirectiveCell umožňují spouštěči, generátoru, pásu rozsahů nebo pásu excelové tabulky konzumovat předkompilované cíle {{#image Key}} přímo; vynecháte-li oba poskytovatele, direktivní buňky zůstanou beze změny

AutofitMode (typ TXLSReportAutofitMode) volí autofit celého listu (xramNone, xramRows, xramColumns nebo xramBoth) aplikovaný jednou po spuštění všech cílů a AutofitAdjustment je dodatečná rezerva (1.0 = žádná, 1.1 = řádky o 10 % vyšší)

Životní cyklus generování a zdroje šablon

TXLSReportLifecyclePhase identifikuje hranice čtení šablony, generování sešitu a generování listu, zatímco TXLSReportLifecycleOutcome rozlišuje vstoupilo, dokončeno, zrušeno a selhalo u zpětných volání

TXLSReportLifecycleContext dodává aktivní sešit a list, stabilní identitu listu, původní a aktuální souřadnice, IXLSReportDataView jen pro čtení, počet cílů a detaily prvního selhání; každé události before předcházející vstupu do události odpovídá párová událost after, i když je generování zrušeno nebo selže

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheet a AfterGenerateSheet pozorují zmrazenou sadu původních listů; strukturální změny vyvolané zpětnými voláními spustí obnovení kompilace bez přidávání nově vytvořených listů do aktuálního běhu

TXLSReportGenerator přijímá sešit, název souboru, stream vlastněný volajícím nebo zašifrovaný soubor a do událostí generování přidává BeforeReadTemplate a AfterReadTemplate; TXLSReportModificationMode volí kompatibilní místní mutaci nebo izolované generování do atomického klonu. Jen pro čtení SourceKind (typ TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStream nebo xrtsEncryptedFile) a TemplateWorkbook hlásí nakonfigurovaný zdroj šablony, zatímco ModificationMode a IncludeResolver lze před během nastavit

Šablony ze souborů a streamů mají výchozí xrmAtomicClone; seekovatelné vstupní streamy obnoví svou původní pozici, streamy pouze pro dopředné čtení se konzumují v ohraničených blocích, streamy volajícího zůstávají otevřené a výstupní streamy či soubory se nahrazují až po úspěšném dokončení

Plánování, kontrola a migrace

TXLSReportPaginationPlanner poskytuje plány KeepTogether, SplitRows, MergeSimilar a BalanceColumns pro pevná zápatí a vyvážený výstup

TXLSReportTemplateChecker poskytuje Check, CheckBand a CheckTableBand; TXLSReportTemplateMigrator poskytuje MigrateText a MigrateWorkbook pro podporované starší formy zástupných znaků

Příklad pro 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;

Příklad pro 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;

Kompletnní spustitelné verze obsahují ukázky Delphi FeatureShowcase a C++Builder XlsxFeatureGallery, které před uvolněním spouštěče ověří stav dokončeno s chybami a počet problémů

Viz také

• Pokročilé pracovní postupy sešitu
• TXLSXWorkbook
• TXLSPaginationModel