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) whose TXLSReportDataSource (kind TXLSReportDataSourceKind: не указан, ячейка, полоса диапазона, полоса таблицы или выражение) и TXLSReportDataParameter описывают источник и его значения, а чей RunControl is the host's IXLSReportRunControl cancellation handle; HasResolver tests a provider key, TryGetTable and RequireTable read cached aliases, TryResolveTable and RequireResolvedTable resolve on demand into a TXLSReportDataResolveResult (status TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFound, or xrdrsDataError), and TryGetState reports a TXLSReportDataSessionState состояния — loading, resolved, not found или data error, тогда как CachedAliasCount and ResolvedAliasCount expose session size

IXLSReportDataView.TryGetValue , Countи Namesнастраивают Values accessors

Relations and lazy table combinators

TXLSReportRowIndexes and TXLSReportRelationIndex хранят номера дочерних строк в корзинах по составным ключам; используйте FindChildRows or CreateChildCursor and inspect BucketCount or IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregate, and TXLSReportJoinKind configure TXLSReportTableFactory, whose row filters compare through 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-диапазона схлопываются

FixedBand заставляет строковые полосы перезаписывать строки под шаблоном вместо вставки новых, что удерживает окружающее содержимое на фиксированной позиции

Полосы диапазонов по строкам и столбцам клонируют ветки обсуждений (threaded comments), когда каждый корень и ответ принадлежат диапазону шаблона; заполнители текста и отображаемого имени вычисляются для каждой записи, скопированные комментарии получают новые идентификаторы и перемапленные идентификаторы родителей, а существующие записи персон книги переиспользуются

Компиляция отклоняет ветки, разрезанные границей шаблона, отсутствующих родителей, дубликаты идентификаторов и недопустимые якоря ячеек до разворачивания; переполнение якоря проверяется до изменения листа, а неудавшийся или отменённый запуск удаляет созданные ветки, восстанавливая состояние шаблона

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

Range and Excel-table bands share ErrorMode, StrictDataAccess, RuntimeLimits, and immutable LastResult snapshots; xremWriteAndContinue записывает как буквальную диагностику только явно устранимые сбои ячеек, фиксирует исходные BandInputRow и фактические выходные координаты и продолжает последующие цели и строки, тогда как структурные сбои, отмена, лимиты ресурсов, колбэки и откат остаются фатальными

TXLSCompiledSheetReportBand.Run создаёт отдельные листы для каждой записи с помощью NameColumn, NamePrefixи DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run создаёт продолжающие листы с помощью NamePrefix и DeleteTemplateAfterRun

Шаблоны всей книги

TXLSReportTemplateTarget и TXLSReportTemplateTargets выбирают ячейки, примечания, гиперссылки, фигуры, верхние и нижние колонтитулы, имена листов, определённые имена и свойства документа

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 описывают скомпилированную поверхность и зарегистрированные пользовательские таблицы

ProcessStructuralDirectives (default True) makes a template 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, ApplyTargetи MissingPolicyобновляют точные директивы изображений ClearDirectiveCell update exact image directives

TXLSReportImageBinder.ApplyTargetV2 привязывает одну директивную ячейку через контракт провайдера V2 и пересылает TXLSReportTransformImageEvent который может переписать разрешённые данные до их записи; сам разрешённый плейсхолдер — это TXLSReportEvaluatedTarget whose TXLSReportEvaluatedTargetKind distinguishes xretNone, xretText, xretValue, and xretFormula; IXLSReportImageCancellation.IsCancellationRequested позволяет долгим провайдерам отслеживать кооперативную отмену

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

TXLSReportImageResult carries a TXLSReportImagePayload whose Kind (TXLSReportImagePayloadKind) selects xripMissing, байты или поток, причём время жизни потока объявляется через TXLSReportImageStreamOwnership: xrisoBorrowed потоки остаются во владении вызывающего и восстанавливают позицию, если поддерживают позиционирование, тогда как xrisoTransferred потоки освобождаются ровно один раз; необязательный SourceWidth, SourceHeight, SourceDpiX, and SourceDpiY фиксируют или переопределяют физическую геометрию источника

xrifNatural uses the source physical size, xrifContain масштабирует и центрирует внутри целевого бокса, xrifCover заполняет бокс с симметричной обрезкой источника, а xrifStretch заполняет его без сохранения пропорций; геометрия PNG, JPEG, GIF, BMP, EMF и WMF читается из ограниченных заголовков без декодирования пикселей

OnTransformImage выполняется после снятия копии данных провайдера и до изменения листа; MaximumImageBytes по умолчанию равен 64 МиБ, а подписи данных, заголовки геометрии, пары размеров и DPI, пределы сторон и пикселей растра, якоря и координаты сетки валидируются до привязки

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

TXLSReportDynamicFormat и TXLSReportFormatEvent позволяют исполнителю применять числовые форматы, высоты строк и ширины столбцов для каждой цели

Многократно используемое выполнение

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgressи TXLSReportRunProgressEvent описывают границы хода выполнения и отмены

TXLSCompiledReportRunner предоставляет Run, RunToStream, RunToFileи RunToEncryptedFile, при этом Cancel, ReportTemplate, State, Progressи OnProgressуправляют многократно используемым выполнением; неудачная проверка вызывает OnFormat до детерминированных операций записи EXLSReportData before deterministic writes

ErrorMode (type TXLSReportErrorMode) defaults to xremStop; xremWriteAndContinue handles only explicit EXLSReportRecoverableData failures and resolver DataError результаты, записывает упорядоченные неизменяемые проблемы в 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 допускает 100 000 хранимых проблем, 512 символов на очищенное сообщение и 16 МиБ памяти под проблемы; задайте положительное пользовательское RuntimeLimits record before a run, and leave RuntimeDiagnosticsSheetName пустым, если не требуется единственный структурированный диагностический лист

Устранимые значения и формулы ячеек становятся буквальными [Report error CODE] message текстом, безопасные цели вне ячеек сохраняют исходное значение, а опциональный диагностический лист помечает эти структурированные проблемы как записанные; сбои имени листа и формулы определённого имени всегда останавливают процесс, поскольку могут изменить структуру книги

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

RunToStream, RunToFile, and RunToEncryptedFile выполняют сериализацию в том же времени жизни запуска и сессии данных, затем публикуют один раз; любой фатальный сбой — отмена, сериализация, частичная запись потока или замена приёмника — сохраняет прежний приёмник целиком и освобождает временное хранилище перед возвратом

Непустой выходной поток должен поддерживать чтение, запись, изменение размера и позиционирование, чтобы откат мог восстановить исходные байты, размер и позицию; снимки до 8 МиБ остаются в памяти, более крупные используют управляемое временное хранилище, а успешный коммит оставляет поток в позиции ноль

Нешифрованный вывод использует исходный формат сгенерированной книги, поэтому шаблон ODS даёт поток или файл ODS с необходимыми метаданными пакета; шифрованный вывод по-прежнему использует шифрованный контейнер Office

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

AutofitMode (type TXLSReportAutofitMode) selects a whole-sheet autofit (xramNone, xramRows, xramColumns, or xramBoth) применяемый один раз после выполнения всех целей, и AutofitAdjustment — дополнительный коэффициент запаса (1.0 = без запаса, 1.1 = строки выше на 10%)

Жизненный цикл генерации и источники шаблонов

TXLSReportLifecyclePhase отмечает границы чтения шаблона, генерации книги и генерации листа, тогда как TXLSReportLifecycleOutcome различает колбэки в состояниях entered, completed, canceled и failed

TXLSReportLifecycleContext предоставляет активную книгу и лист, стабильную идентичность листа, исходные и текущие координаты, доступный только для чтения IXLSReportDataView, количество целей и детали первой ошибки; каждое наступившее before-событие получает парное after-событие, даже когда генерация отменяется или завершается сбоем

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

TXLSReportGenerator принимает книгу, имя файла, поток во владении вызывающего или зашифрованный файл и добавляет BeforeReadTemplate plus AfterReadTemplate to the generation events; TXLSReportModificationMode выбирает совместимое изменение на месте или изолированную генерацию через атомарный клон. Режим только для чтения SourceKind (type TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStream, or xrtsEncryptedFile) and TemplateWorkbook сообщают настроенный источник шаблона, тогда как ModificationMode and IncludeResolver are settable before a run

File and stream templates default to 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;

См. также

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 содержат полные запускаемые версии, которые проверяют состояние «завершено с ошибками» и количество проблем перед освобождением раннера

See also

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