컴파일된 보고 API

The lxReport 유닛은 자리 표시자와 구조적 보고 밴드를 한 번 컴파일한 다음, 생성된 통합 문서 개체를 다시 검색하지 않고 경계가 있는 커서를 통해 호출자가 소유한 데이터를 적용합니다

표 및 커서 계약

제어된 쿼리 공급자

IXLSReportQueryExecutor.ExecuteReadOnly 는 쿼리 실행을 호스트 소유로 유지하고 애플리케이션 코드가 등록한 정의만 허용합니다

TXLSReportQueryParameter, TXLSReportQueryParameters및 TXLSReportQueryDefinition 은 Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameter및 ClearParameters

TXLSReportQueryProvider 는 RegisterQuery, RemoveQuery, Clear및 TryGetTable을 사용하며, Count, Definitions및 MaximumTimeoutMS 는 허용 목록과 시간 제한 상한을 노출합니다

실행별 데이터 세션

IXLSReportDataSession 은 보고서 실행 하나 뒤에서 동작하는 격리된 lazy 캐시입니다. DeclareRequest 는 TXLSReportDataRequest 를 등록하는데(kind는 TXLSReportDataRequestKind: xrdrkNamed 또는 xrdrkUser), 이 요청의 TXLSReportDataSource (kind는 TXLSReportDataSourceKind: unspecified, cell, range band, table band, expression)와 TXLSReportDataParameter 목록이 소스와 그 값을 기술하고, RunControl 은 호스트의 IXLSReportRunControl 취소 핸들입니다. HasResolver 는 공급자 키를 검사하고, TryGetTable 과 RequireTable 은 캐시된 별칭을 읽으며, TryResolveTable 과 RequireResolvedTable 은 필요 시 TXLSReportDataResolveResult 로 해석하고(status는 TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFound, xrdrsDataError), TryGetState 는 loading, resolved, not found, data error 중 하나의 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-range 구분 행을 정리합니다

FixedBand 는 행 밴드가 새 행을 삽입하는 대신 템플릿 아래의 기존 행을 덮어쓰게 하여 주변 콘텐츠를 고정 위치에 유지합니다

행과 열 범위 밴드는 모든 루트와 답글이 템플릿 범위 안에 있을 때 스레드 댓글 대화를 클론합니다. 텍스트와 표시 이름 자리 표시자는 레코드마다 평가되고, 복사된 댓글에는 새 식별자와 재매핑된 부모 식별자가 부여되며, 기존 통합 문서 person 레코드는 재사용됩니다

컴파일은 템플릿 경계에 걸쳐 분할된 대화, 누락된 부모, 중복 식별자, 잘못된 셀 앵커를 확장 전에 거부합니다. 앵커 오버플로는 워크시트 변경 전에 검사하고, 실패하거나 취소된 실행은 생성된 대화를 제거하면서 템플릿 상태를 복원합니다

TXLSCompiledTableReportBand.Run 은 표 메타데이터를 보존하면서 하나의 Excel 표 데이터 템플릿 행을 확장합니다. TableName, Sheet, SheetIndex, ExcelTable, TemplateRow및 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 속성을 통해 통합 문서에 계속 접근할 수 있게 합니다

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 를 전달합니다. 해석된 자리 표시자 자체는 TXLSReportEvaluatedTarget 이며 그 TXLSReportEvaluatedTargetKind 가 xretNone, xretText, xretValue, xretFormula를 구분합니다. IXLSReportImageCancellation.IsCancellationRequested 로 오래 실행되는 공급자도 협조적 취소를 관찰할 수 있습니다

IXLSReportImageDataProviderV2.GetImage 는 안정적인 워크시트 식별자, 컴파일된 대상, 밴드·테이블 이름, 논리 행과 커서 행, 읽기 전용 현재 행 뷰, 지시문·앵커 셀, EMU 단위의 대상 크기와 오프셋, TXLSReportImageRequest 을 담은 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이고, 페이로드 서명, 지오메트리 헤더, 크기·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 실패와 resolver 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 텍스트가 되고, 셀이 아닌 안전한 대상은 원래 값을 유지하며, 선택적 진단 워크시트는 이런 구조화된 이슈를 기록된 것으로 표시합니다. 워크시트 이름과 defined-name 수식 실패는 통합 문서 구조를 바꿀 수 있으므로 항상 실행을 중단합니다

resolver가 선언한 데이터 오류, 식의 0 나누기, 잘못된 정규식은 안정적인 provider 또는 expression 카테고리를 사용합니다. resolver가 던진 예외와 모든 콜백, 취소, 리소스 한도, 롤백, 직렬화, 보안, 구조적 실패는 여전히 치명적입니다

RunToStream, RunToFile, RunToEncryptedFile 은 동일한 실행·데이터 세션 수명 안에서 직렬화를 준비한 뒤 한 번에 게시합니다. 치명적 실패, 취소, 직렬화 실패, 부분 스트림 쓰기, 대상 교체 실패가 있으면 기존 대상을 온전히 보존하고 임시 저장소를 해제한 다음 반환합니다

비어 있지 않은 출력 스트림은 롤백이 원래 바이트·크기·위치를 복원할 수 있도록 읽기, 쓰기, 크기 조정, 탐색이 모두 가능해야 합니다. 최대 8 MiB까지의 스냅샷은 메모리에 유지되고 그보다 큰 스냅샷은 관리되는 임시 저장소를 사용합니다. 커밋이 성공하면 스트림은 위치 0에 놓입니다

암호화되지 않은 출력은 생성된 통합 문서의 원본 포맷을 따르므로, 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 는 호환되는 제자리 변경 또는 격리된 atomic-clone 생성을 선택합니다. 읽기 전용 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에는 runner를 해제하기 전에 completed-with-errors 상태와 이슈 개수를 검증하는 완전히 실행 가능한 버전이 들어 있습니다

참고 항목

• 고급 통합 문서 워크플로
• TXLSXWorkbook
• TXLSPaginationModel