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 є обробник скасування IXLSReportRunControl хоста; HasResolver перевіряє ключ постачальника, TryGetTable і RequireTable читають кешовані аліаси, TryResolveTable і RequireResolvedTable розв'язують на вимогу в TXLSReportDataResolveResult (стан TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFoundабо xrdrsDataError), а TryGetState повідомляє TXLSReportDataSessionState — завантаження, розв'язано, не знайдено чи помилка даних, при цьому CachedAliasCount і ResolvedAliasCount розкривають розмір сеансу

IXLSReportDataView.TryGetValue шукає одне іменоване значення без викидання винятків, доповнюючи індексовані аксесори Count, Namesі Values accessors

Зв'язки та ліниві комбінатори таблиць

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 розширює один рядок шаблону даних таблиці Excel, зберігаючи метадані таблиці; перевіряйте TXLSEmptyBandPolicy, xreKeepTemplate , xreClearTemplate , xreDeleteTemplate , DeleteLastRow і BandHeight рядків розширеного блоку після того, як його копії розташуються, тож кінцеві розділові рядки X-range схлопуються

FixedBand змушує смуги рядків перезаписувати рядки під шаблоном замість вставляння нових, що тримає навколишній вміст на фіксованій позиції

TXLSCompiledTableReportBand.Run розгортає один рядок шаблону даних таблиці Excel, зберігаючи метадані таблиці; перевіряйте TableName, Sheet, SheetIndex, ExcelTable, TemplateRow, and State, а також налаштовуйте ті самі властивості зображень V2, які відкривають смуги діапазонів

Смуги діапазонів і таблиць Excel спільно використовують ErrorMode, StrictDataAccess, RuntimeLimitsі незмінні знімки LastResult ; xremWriteAndContinue записує як буквену діагностику лише явні відновлювані збої клітинок, фіксує вихідний BandInputRow і фактичні вихідні координати та продовжує пізніші цілі й рядки, тоді як структурні збої, скасування, ліміти ресурсів, збої зворотних викликів і відкату залишаються фатальними

TXLSCompiledSheetReportBand.Run створює аркуші для кожного запису за допомогою NameColumn, NamePrefixі DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run створює аркуші продовження за допомогою NamePrefix і DeleteTemplateAfterRun

Шаблони цілої книги

TXLSReportTemplateTarget і TXLSReportTemplateTargets обирають комірки, коментарі, гіперпосилання, фігури, верхні та нижні колонтитули, імена аркушів, іменовані діапазони та властивості документа

TXLSCompiledReportTemplate.Compile фіксує цілі та вирази, Analyze повертає адресовані TXLSReportIssues, перевантаження Run застосовують значення, а WriteDiagnostics записує проблеми на аркуш; TargetAreas, TargetCountі UserTableCount описують скомпільовану поверхню та зареєстровані таблиці користувача

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

TXLSReportIssueKind, TXLSReportIssueі TXLSReportIssues визначають некоректний, відсутній, недійсний, невідомий або циклічний вміст плейсхолдерів із координатами цілі та комірки

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

IXLSReportIncludeResolver.Resolve постачає іменовані фрагменти, а його прапорець Immutable дозволяє безпечне повторне використання; TXLSReportIncludeLibrary надає Add, Remove, Clear, Freeze, Resolve, Countі Immutable

IXLSReportImageProvider.TryGetImage повертає TXLSReportImageValue , налаштований TXLSReportImageFit; TXLSReportMissingImagePolicy керує відсутніми ресурсами, тоді як TXLSReportImageBinder.Apply, ApplyTarget, MissingPolicyі ClearDirectiveCell оновлюють точні директиви зображень

TXLSReportImageBinder.ApplyTargetV2 прив'язує одну директивну клітинку через контракт постачальника V2 і передає TXLSReportTransformImageEvent , який може переписати розв'язаний payload до того, як він буде записаний; сам розв'язаний заповнювач є TXLSReportEvaluatedTarget , чий TXLSReportEvaluatedTargetKind розрізняє xretNone, xretText, xretValueі xretFormula; IXLSReportImageCancellation.IsCancellationRequested дозволяє довготривалим постачальникам бачити кооперативне скасування

IXLSReportImageDataProviderV2.GetImage отримує TXLSReportImageRequest зі стабільною ідентичністю аркуша, скомпільованою ціллю, назвами смуги й таблиці, логічними рядками та рядками курсора, view поточного рядка лише для читання, клітинками директиви й якоря, розмірами цілі та зміщеннями в EMU і IXLSReportImageCancellation

TXLSReportImageResult несе TXLSReportImagePayload , чиїй Kind (TXLSReportImagePayloadKind) обирає xripMissing, байти або потік, причому час життя потоку визначає TXLSReportImageStreamOwnership: потоки xrisoBorrowed залишаються власністю викликача й відновлюють позицію, якщо підтримують пошук, а потоки 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

TXLSReportDynamicFormat і TXLSReportFormatEvent дозволяють виконавцю застосовувати числові формати, висоти рядків і ширини стовпців для кожної цілі

Багаторазове виконання

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgressі TXLSReportRunProgressEvent описують межі прогресу та скасування

TXLSCompiledReportRunner надає Run, RunToStream, RunToFile, RunToEncryptedFileі 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 порожнім, якщо не потрібен один структурований аркуш діагностики

Відновлювані значення та формули клітинок стають буквеним текстом [Report error CODE] message , безпечні не-клітинкові цілі зберігають початкове значення, а опційний аркуш діагностики позначає ці структуровані проблеми як записані; збої назв аркушів і формул іменованих назв завжди зупиняють виконання, бо вони можуть змінити структуру книги

Оголошені резолвером помилки даних, ділення на нуль у виразах і недійсні регулярні вирази використовують стабільні категорії постачальника чи виразу; викинуті винятки резолвера та всі збої зворотних викликів, скасування, лімітів ресурсів, відкату, серіалізації, безпеки та структури залишаються фатальними

RunToStream, RunToFileі RunToEncryptedFile виконують стадію серіалізації всередині того самого часу життя виконання та сеансу даних, а потім публікують один раз; будь-який фатальний, скасований, серіалізаційний, частковий потоковий запис чи збій заміни призначення зберігає повний попередній вивід і звільняє тимчасове сховище до повернення

Непорожній вихідний потік має бути читабельним, придатним для запису, зміни розміру та пошуку, щоб відкат міг відновити його початкові байти, розмір і позицію; знімки до 8 MiB залишаються в пам'яті, а більші використовують кероване тимчасове сховище, при цьому успішна фіксація залишає потік у позиції нуль

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

ImageProvider зберігає початковий контракт сумісності; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicyі ClearImageDirectiveCell дозволяють виконавцю, генератору, смузі діапазону чи смузі таблиці Excel споживати попередньо скомпільовані цілі {{#image Key}} безпосередньо; якщо обидва постачальники пропущені, ті директивні клітинки залишаються без змін

AutofitMode (тип TXLSReportAutofitMode) обирає автофігур ціле аркуша (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 обирає сумісну зміну на місці або ізольовану генерацію в атомарному клоні. Лише для читання SourceKind (тип TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStreamабо xrtsEncryptedFile) і TemplateWorkbook повідомляють налаштоване джерело шаблону, тоді як ModificationMode і IncludeResolver можна задавати до виконання

Шаблони з файлів і потоків типово використовують xrmAtomicClone; потоки введення з підтримкою пошуку відновлюють початкову позицію, потоки лише вперед споживаються обмеженими блоками, потоки викликача залишаються відкритими, а вихідні потоки чи файли замінюються лише після успішного завершення

Планування, перевірка та міграція

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

TXLSReportTemplateChecker надає Check, CheckBandі CheckTableBand; TXLSReportTemplateMigrator надає MigrateText і MigrateWorkbook для підтримуваних застарілих форм плейсхолдерів

Приклад

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 example

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