API за компилирани отчети

Единицата lxReport компилира веднъж заместителите и структурните отчетни ленти, след което прилага данни, притежавани от извикващия код, чрез ограничени курсори, без повторно сканиране на генерираните обекти на работната книга

Договори за таблици и курсори

Контролирани доставчици на заявки

IXLSReportQueryExecutor.ExecuteReadOnly запазва изпълнението на заявките притежавано от хоста и приема само дефиниции, регистрирани от приложния код

TXLSReportQueryParameter, TXLSReportQueryParameters и TXLSReportQueryDefinition разкриват Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameter и ClearParameters

TXLSReportQueryProvider използва RegisterQuery, RemoveQuery, Clear и TryGetTable, като Count, Definitions и MaximumTimeoutMS разкриват белия списък и горната граница на времето за изчакване

Сесии с данни за отделно изпълнение

IXLSReportDataSession е изолираният отложен кеш зад едно изпълнение на отчет: DeclareRequest регистрира TXLSReportDataRequest (вид TXLSReportDataRequestKind: xrdrkNamed или xrdrkUser), чийто TXLSReportDataSource (вид TXLSReportDataSourceKind: неуточнен, клетка, диапазонна лента, лента на таблица или израз) и списъкът TXLSReportDataParameter описват източника и неговите стойности, а RunControl е handlerът за отмяна IXLSReportRunControl на хоста; HasResolver проверява ключ на доставчик, TryGetTable и RequireTable четат кеширани псевдоними, TryResolveTable и RequireResolvedTable разрешават при поискване в TXLSReportDataResolveResult (статус TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFound или xrdrsDataError), а TryGetState докладва TXLSReportDataSessionState — зареждане, разрешено, не е намерено или грешка в данните; CachedAliasCount и ResolvedAliasCount разкриват размера на сесията

IXLSReportDataView.TryGetValue търси една именувана стойност, без да повдига изключение, и допълва индексираните достъпи Count, Names и Values

Връзки и отложени таблични комбинатори

TXLSReportRowIndexes и TXLSReportRelationIndex съхраняват номерата на дъщерните редове в кофи с многокомпонентни ключове; използвайте FindChildRows или CreateChildCursor и инспектирайте BucketCount или IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregate и TXLSReportJoinKind конфигурират TXLSReportTableFactory, чиито редови филтри сравняват чрез TXLSReportFilterOperator (xrfoEqual, xrfoNotEqual, xrfoGreater, xrfoGreaterEqual, xrfoLess, xrfoLessEqual, xrfoContains, xrfoStartsWith, xrfoEndsWith)

Именувани и изрични диапазонни ленти

TXLSReportBandKind избира разширяване по редове, колони или кръстосани таблици, а TXLSReportBandState отчита състоянието на жизнения цикъл

TXLSCompiledReportBand приема точно определено име на обхват или CreateForRange, след което се разширява чрез претоварванията на Run; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCount и State разкриват компилирания план

EmptyBandPolicy (тип TXLSEmptyBandPolicy) контролира какво прави лентата с редовете си от шаблона, когато наборът данни е празен — xreKeepTemplate оставя редовете недокоснати, xreClearTemplate изчиства клетките на лентата заедно с заместителите, а xreDeleteTemplate изтрива шаблонните редове; DeleteLastRow премахва последните BandHeight реда на разширения блок, след като копията му заемат мястото си, така че завършващите разделителни редове на X-диапазон се свиват

FixedBand кара редовите ленти да презаписват редовете под шаблона, вместо да вмъкват нови, така че заобикалящото съдържание остава на фиксирана позиция

TXLSCompiledTableReportBand.Run разширява един шаблонен ред на данни на Excel таблица, като запазва метаданните на таблицата; инспектирайте TableName, Sheet, SheetIndex, ExcelTable, TemplateRow и State

Диапазонните ленти и лентите на Excel таблиците споделят ErrorMode, StrictDataAccess, RuntimeLimits и неизменяемите снимки в LastResult; xremWriteAndContinue записва като литерална диагностика само изрично възстановимите повреди в клетки, записва изходния BandInputRow и реалните изходни координати и продължава със следващите цели и редове, докато структурните повреди, отменянето, ограниченията на ресурсите, повредите в обратните извиквания и rollback остават фатални

TXLSCompiledSheetReportBand.Run създава листове за всеки запис с помощта на NameColumn, NamePrefix и DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run създава продължаващи листове с помощта на NamePrefix и DeleteTemplateAfterRun

Шаблони за цели работни книги

TXLSReportTemplateTarget и TXLSReportTemplateTargets избират клетки, коментари, хипервръзки, форми, горни и долни колонтитули, имена на листове, дефинирани имена и свойства на документа

TXLSCompiledReportTemplate.Compile улавя целите и изразите, Analyze връща адресирани TXLSReportIssues, претоварванията на Run прилагат стойностите, а WriteDiagnostics записва проблемите в работен лист; TargetAreas и TargetCount описват компилираната повърхност

ProcessStructuralDirectives (по подразбиране True) кара Run на шаблона да изпълни структурните директиви {{#delete}} и {{#format}} след прилагането на целите със стойности — TXLSReportDirectiveProcessor, стоещ зад това, разбира диапазоните, прилага ги и докладва колко е обработил чрез AppliedCount; CreateEncrypted отваря криптиран шаблон с паролата му и го компилира, като запазва работната книга достъпна през свойството Workbook

TXLSReportIssueKind, TXLSReportIssue и TXLSReportIssues идентифицират малформирано, липсващо, невалидно, неизвестно или циклично съдържание на заместители с координати на целта и клетката

Включвания, изображения и форматиране

IXLSReportIncludeResolver.Resolve доставя именувани фрагменти, а неговият флаг Immutable позволява безопасно преизползване; TXLSReportIncludeLibrary предоставя Add, Remove, Clear, Freeze, Resolve, Count и Immutable

IXLSReportImageProvider.TryGetImage връща TXLSReportImageValue, конфигуриран от TXLSReportImageFit; TXLSReportMissingImagePolicy контролира липсващите ресурси, докато TXLSReportImageBinder.Apply, MissingPolicy и ClearDirectiveCell актуализират точните директиви за изображения

TXLSReportImageBinder.ApplyTargetV2 обвързва една директивна клетка чрез V2 договора за доставчици и препраща TXLSReportTransformImageEvent, който може да пренапише разрешения payload, преди да заеме мястото си; самият разрешен заместител е TXLSReportEvaluatedTarget, чийто TXLSReportEvaluatedTargetKind разграничава xretNone, xretText, xretValue и xretFormula; IXLSReportImageCancellation.IsCancellationRequested позволява на дълго работещите доставчици да следят кооперативно отмяна

IXLSReportImageDataProviderV2.GetImage получава TXLSReportImageRequest със стабилна идентичност на листа, компилирана цел, имена на лента и таблица, логически и cursor редове, изглед на текущия ред само за четене, директивна и котвена клетка, размери и отмествания на целта в EMU и IXLSReportImageCancellation

TXLSReportImageResult носи TXLSReportImagePayload, чийто Kind (TXLSReportImagePayloadKind) избира xripMissing, байтове или поток, като животът на потока се декларира от TXLSReportImageStreamOwnership: xrisoBorrowed потоците остават собственост на извикващия и възстановяват позицията си, когато са seekable, а xrisoTransferred потоците се освобождават точно веднъж; незадължителните SourceWidth, SourceHeight, SourceDpiX и SourceDpiY потвърждават или презаписват физическата геометрия на източника

xrifNatural използва физическия размер на източника, xrifContain мащабира и центрира в целевата кутия, xrifCover запълва кутията със симетрично изрязване на източника, а xrifStretch я запълва без запазване на пропорциите; геометрията на PNG, JPEG, GIF, BMP, EMF и WMF се чете от ограничени заглавки, без декодиране на пиксели

OnTransformImage се изпълнява след снимката на данните от доставчика и преди промяната на работния лист; MaximumImageBytes по подразбиране е 64 MiB, а подписите на payload, геометричните заглавки, двойките размер и DPI, ограниченията за растерна страна и пиксели, котвите и координатите в мрежата се валидират преди обвързване

TXLSXImage.OffsetXEMU и OffsetYEMU запазват позицията на изображение в неговата клетка или абсолютна котва през XLSX и ODS roundtrip цикли

TXLSReportDynamicFormat и TXLSReportFormatEvent позволяват на изпълнителя да прилага числови формати, височини на редове и ширини на колони за всяка цел

Преизползваемо изпълнение

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgress и TXLSReportRunProgressEvent описват границите на напредъка и отмяната

TXLSCompiledReportRunner разкрива Run, RunToStream, RunToFile и Cancel, като ReportTemplate, State, Progress, OnProgress и OnFormat контролират преизползваемото изпълнение; неуспешната валидация повдига EXLSReportData преди детерминирано записване

ErrorMode (тип TXLSReportErrorMode) по подразбиране е xremStop; xremWriteAndContinue обработва само изричните повреди EXLSReportRecoverableData и резултатите DataError от резолвера, записва подредени неизменяеми проблеми в LastResult (един IXLSReportRunResult, разкриващ State, AppliedCount, IssueCount, индексирани Issues и FailureClassName / FailureMessage на фатална повреда), чийто снимки TXLSReportRuntimeIssue разкриват своята Category (едно TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProvider или xrricExpression) и докладват TargetIndex, SheetName, Col и дали проблемът вече е бил WasWritten в изхода, а завършва като xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults позволява 100 000 запазени проблема, по 512 знака на дезинфекцирано съобщение и 16 MiB памет за проблеми; задайте положителен персонализиран запис RuntimeLimits преди изпълнение и оставете RuntimeDiagnosticsSheetName празен, освен ако не ви трябва един структуриран diagnostics работен лист

Възстановимите стойности и формули в клетки стават литерален текст [Report error CODE], безопасните цели извън клетките запазват оригиналната си стойност, а незадължителният diagnostics работен лист маркира тези структурирани проблеми като записани; повредите в имената на листове и във формулите на дефинирани имена винаги спират изпълнението, защото могат да променят структурата на работната книга

Декларираните от резолвера грешки в данните, деленето на нула в изразите и невалидните регулярни изрази използват стабилни категории за доставчик или израз; хвърлените изключения от резолвера и всички повреди в обратни извиквания, отмяна, ограничения на ресурсите, rollback, сериализация, сигурност и структура остават фатални

RunToStream, RunToFile и RunToEncryptedFile подготвят сериализацията в рамките на същия живот на изпълнението и сесията с данни, след което публикуват веднъж; всяка фатална повреда, отмяна, сериализация, частичен запис в поток или замяна на целта запазва пълната предишна цел и освобождава временното хранилище, преди да се върне

Непразен изходен поток трябва да е четим, записваем, с променлив размер и seekable, за да може rollback да възстанови оригиналните му байтове, размер и позиция; снимките до 8 MiB остават в паметта, по-големите използват управлявано временно хранилище, а успешен commit оставя потока на позиция нула

Некриптираният изход използва изходния формат на генерираната работна книга, така че ODS шаблон дава ODS поток или файл с необходимите му пакетни метаданни; криптираният изход продължава да използва криптирания Office контейнер

ImageProvider запазва оригиналния договор за съвместимост; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicy и ClearImageDirectiveCell позволяват на изпълнител, генератор, диапазонна лента или лента на Excel таблица да консумира директно предварително компилирани цели {{#image Key}}; ако липсват и двата доставчика, тези директивни клетки остават непроменени

AutofitMode (тип TXLSReportAutofitMode) избира autofit на целия лист (xramNone, xramRows, xramColumns или xramBoth), прилаган веднъж след изпълнението на всички цели, а AutofitAdjustment е допълнителен коефициент за запас (1.0 = без, 1.1 = 10% по-високи редове)

Жизнен цикъл на генерирането и източници на шаблони

TXLSReportLifecyclePhase идентифицира границите на четене на шаблона, генериране на работна книга и генериране на работен лист, а TXLSReportLifecycleOutcome разграничава влезли, завършени, отменени и неуспешни обратни извиквания

TXLSReportLifecycleContext доставя активната работна книга и работен лист, стабилна идентичност на листа, оригинални и текущи координати, изглед IXLSReportDataView само за четене, брой цели и подробности за първата повреда; всяко влязло before събитие получава сдвоено after събитие, дори когато генерирането е отменено или се провали

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheet и AfterGenerateSheet наблюдават замразено множество от оригинални работни листове; структурните промени, задвижвани от обратни извиквания, задействат обновяване на компилацията, без да добавят новосъздадени листове към текущото изпълнение

TXLSReportGenerator приема работна книга, име на файл, поток, притежаван от извикващия, или криптиран файл и добавя BeforeReadTemplate и AfterReadTemplate към събитията на генерирането; TXLSReportModificationMode избира съвместима мутация на място или генериране в изолиран атомарен клонинг. Read-only SourceKind (тип TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStream или xrtsEncryptedFile) и TemplateWorkbook докладват конфигурирания източник на шаблона, докато ModificationMode и IncludeResolver се задават преди изпълнение

Файловите и потоковите шаблони по подразбиране използват xrmAtomicClone; seekable входните потоци възстановяват оригиналната си позиция, forward-only потоците се консумират в ограничени блокове, потоците на извикващия остават отворени, а изходните потоци или файлове се заменят само след успешно завършване

Планиране, проверка и миграция

TXLSReportPaginationPlanner предоставя планове KeepTogether, SplitRows, MergeSimilar и BalanceColumns за фиксирани колонтитули и балансиран изход

TXLSReportTemplateChecker предоставя Check, CheckBand и CheckTableBand; TXLSReportTemplateMigrator предоставя MigrateText и MigrateWorkbook за поддържани наследени форми на заместители

Пример за 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;

Пример за 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;

Delphi примерът FeatureShowcase и C++Builder примерът XlsxFeatureGallery съдържат пълни работещи версии, които проверяват състоянието "завършено с грешки" и броя на проблемите, преди да освободят изпълнителя

Свързани теми

• Разширени работни процеси за работни книги
• TXLSXWorkbook
• TXLSPaginationModel