Interfejs API raportowania skompilowanego

Jednostka lxReport kompiluje symbole zastępcze i strukturalne pasma raportu jednorazowo, a następnie stosuje dane należące do wywołującego przez ograniczone kursory, bez ponownego skanowania wygenerowanych obiektów skoroszytu

Kontrakty tabel i kursorów

Kontrolowane dostawcy zapytań

IXLSReportQueryExecutor.ExecuteReadOnly utrzymuje wykonywanie zapytań po stronie hosta i przyjmuje tylko definicje zarejestrowane przez kod aplikacji

TXLSReportQueryParameter, TXLSReportQueryParametersi TXLSReportQueryDefinition udostępniają Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameteri ClearParameters

TXLSReportQueryProvider używa RegisterQuery, RemoveQuery, Cleari TryGetTable, przy czym Count, Definitionsi MaximumTimeoutMS udostępniają listę dozwolonych zapytań i górny limit czasu

Sesje danych pojedynczego uruchomienia

IXLSReportDataSession to izolowany leniwy cache stojący za jednym uruchomieniem raportu: DeclareRequest rejestruje TXLSReportDataRequest (rodzaj TXLSReportDataRequestKind: xrdrkNamed albo xrdrkUser), którego TXLSReportDataSource (rodzaj TXLSReportDataSourceKind: nieokreślony, komórka, pasmo zakresu, pasmo tabeli albo wyrażenie) i lista TXLSReportDataParameter opisują źródło i jego wartości, a którego RunControl to uchwyt anulowania IXLSReportRunControl po stronie gospodarza; HasResolver testuje klucz dostawcy, TryGetTable i RequireTable czytają cache'owane aliasy, TryResolveTable i RequireResolvedTable rozwiązują na żądanie do TXLSReportDataResolveResult (status TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFoundalbo xrdrsDataError), a TryGetState raportuje TXLSReportDataSessionState — ładowanie, rozwiązane, nie znaleziono albo błąd danych — przy czym CachedAliasCount i ResolvedAliasCount ujawniają rozmiar sesji

IXLSReportDataView.TryGetValue wyszukuje jedną nazwaną wartość bez rzucania wyjątku, uzupełniając indeksowane akcesory Count, Namesi Values accessors

Relacje i leniwe kombinary tabel

TXLSReportRowIndexes i TXLSReportRelationIndex przechowują numery wierszy podrzędnych w zasobnikach kluczy złożonych; użyj FindChildRows lub CreateChildCursor i sprawdź BucketCount lub IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregatei TXLSReportJoinKind konfigurują TXLSReportTableFactory, którego filtry wierszy porównują przez TXLSReportFilterOperator (xrfoEqual, xrfoNotEqual, xrfoGreater, xrfoGreaterEqual, xrfoLess, xrfoLessEqual, xrfoContains, xrfoStartsWith, xrfoEndsWith)

Nazwane i jawne pasma zakresów

TXLSReportBandKind wybiera rozwijanie wiersza, kolumny lub tabeli krzyżowej, a TXLSReportBandState raportuje stan cyklu życia

TXLSCompiledReportBand przyjmuje dokładną nazwę zdefiniowaną lub CreateForRange, a następnie rozwija się przez przeciążenia Run ; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCounti State udostępniają skompilowany plan

EmptyBandPolicy (typ TXLSEmptyBandPolicy) steruje tym, co pasmo robi ze swoimi wierszami szablonu, gdy zbiór danych jest pusty — xreKeepTemplate zostawia wiersze bez zmian, xreClearTemplate czyści komórki pasma wraz z placeholderami, a xreDeleteTemplate usuwa wiersze szablonu; DeleteLastRow usuwa ostatnie BandHeight wierszy rozwiniętego bloku po tym, jak jego kopie wylądują, więc końcowe wiersze separatora zakresu X się zwijają

FixedBand sprawia, że pasma wierszy nadpisują wiersze poniżej szablonu zamiast wstawiać nowe, dzięki czemu otaczająca zawartość zostaje na stałej pozycji

Pasma zakresów wierszy i kolumn klonują wątkowe konwersacje komentarzy, gdy każdy korzeń i odpowiedź należy do zakresu szablonu; placeholdery tekstu i nazwy wyświetlanej są wyliczane per rekord, skopiowane komentarze otrzymują nowe identyfikatory i przemapowane identyfikatory rodziców, a istniejące rekordy osób skoroszytu są ponownie używane

Kompilacja odrzuca przed rozwinięciem konwersacje rozdzielone przez granicę szablonu, brakujących rodziców, zduplikowane identyfikatory i nieprawidłowe zakotwiczenia komórek; przepełnienie zakotwiczenia jest sprawdzane przed mutacją arkusza, a nieudany albo anulowany przebieg usuwa wygenerowane konwersacje, przywracając stan szablonu

TXLSCompiledTableReportBand.Run rozwija jeden wiersz szablonu danych tabeli programu Excel z zachowaniem metadanych tabeli; sprawdź TableName, Sheet, SheetIndex, ExcelTable, TemplateRowi State, a także skonfiguruj te same właściwości obrazów V2, które udostępniają pasma zakresów

Pasma zakresów i tabel Excela współdzielą ErrorMode, StrictDataAccess, RuntimeLimitsoraz niezmienne migawki LastResult ; xremWriteAndContinue zapisuje jako literały tylko jawne, odwracalne błędy komórek, rejestruje źródłowy BandInputRow i rzeczywiste współrzędne wyjściowe i kontynuuje kolejne cele i wiersze, podczas gdy błędy strukturalne, anulowania, limitów zasobów, callbacków i rollbacku pozostają śmiertelne

TXLSCompiledSheetReportBand.Run tworzy arkusze per rekord przy użyciu NameColumn, NamePrefixi DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run tworzy arkusze kontynuacji przy użyciu NamePrefix i DeleteTemplateAfterRun

Szablony całego skoroszytu

TXLSReportTemplateTarget i TXLSReportTemplateTargets wybierają komórki, komentarze, hiperłącza, kształty, nagłówki i stopki, nazwy arkuszy, nazwy zdefiniowane i właściwości dokumentu

TXLSCompiledReportTemplate.Compile przechwytuje cele i wyrażenia, Analyze zwraca zaadresowane TXLSReportIssues, przeciążenia Run stosują wartości, a WriteDiagnostics zapisuje problemy do arkusza; TargetAreas, TargetCounti UserTableCount opisują skompilowaną powierzchnię i zarejestrowane tabele użytkownika

ProcessStructuralDirectives (domyślnie True) sprawia, że Run szablonu wykonuje strukturalne dyrektywy {{#delete}} i {{#format}} po zastosowaniu celów wartości — stojący za tym TXLSReportDirectiveProcessor analizuje zakresy, stosuje je i raportuje przez AppliedCount , ile ich obsłużył — a CreateEncrypted otwiera zaszyfrowany szablon z hasłem i kompiluje go, pozostawiając skoroszyt dostępny przez właściwość Workbook property

TXLSReportIssueKind, TXLSReportIssuei TXLSReportIssues identyfikują błędną, brakującą, nieprawidłową, nieznaną lub cykliczną zawartość symboli zastępczych wraz ze współrzędnymi celu i komórki

Fragmenty dołączane, obrazy i formatowanie

IXLSReportIncludeResolver.Resolve dostarcza nazwane fragmenty, a jego flaga Immutable umożliwia bezpieczne ponowne użycie; TXLSReportIncludeLibrary udostępnia Add, Remove, Clear, Freeze, Resolve, Counti Immutable

IXLSReportImageProvider.TryGetImage zwraca TXLSReportImageValue skonfigurowany przez TXLSReportImageFit; TXLSReportMissingImagePolicy kontroluje brakujące zasoby, a TXLSReportImageBinder.Apply, ApplyTarget, MissingPolicyi ClearDirectiveCell aktualizują dokładne dyrektywy obrazów

TXLSReportImageBinder.ApplyTargetV2 wiąże jedną komórkę dyrektywy przez kontrakt dostawcy V2 i przekazuje dalej TXLSReportTransformImageEvent , który może przepisać rozwiążany payload, zanim trafi na miejsce; sam rozwiązany placeholder to TXLSReportEvaluatedTarget , którego TXLSReportEvaluatedTargetKind rozróżnia xretNone, xretText, xretValuei xretFormula; IXLSReportImageCancellation.IsCancellationRequested pozwala długotrwałym dostawcom obserwować kooperatywne anulowanie

IXLSReportImageDataProviderV2.GetImage otrzymuje TXLSReportImageRequest ze stabilną tożsamością arkusza, skompilowanym celem, nazwami pasma i tabeli, wierszami logicznym i kursora, widokiem bieżącego wiersza tylko do odczytu, komórkami dyrektywy i kotwicy, wymiarami i przesunięciami celu w EMU oraz IXLSReportImageCancellation

TXLSReportImageResult niesie TXLSReportImagePayload , którego Kind (TXLSReportImagePayloadKind) wybiera xripMissing, bajty albo strumień, przy czym czas życia strumienia deklaruje TXLSReportImageStreamOwnership: strumienie xrisoBorrowed pozostają własnością wywołującego i przywracają pozycję, jeśli są przewijalne, a strumienie xrisoTransferred są zwalniane dokładnie raz; opcjonalne SourceWidth, SourceHeight, SourceDpiXi SourceDpiY asertują albo nadpisują fizyczną geometrię źródła

xrifNatural używa fizycznego rozmiaru źródła, xrifContain skaluje i wyśrodkowuje w docelowym polu, xrifCover wypełnia pole z symetrycznym przycięciem źródła, a xrifStretch wypełnia je bez zachowania proporcji; geometria PNG, JPEG, GIF, BMP, EMF i WMF jest odczytywana z ograniczonych nagłówków bez dekodowania pikseli

OnTransformImage działa po zrobieniu migawki danych dostawcy, a przed mutacją arkusza; MaximumImageBytes ma domyślnie 64 MiB, a podpisy payloadów, nagłówki geometrii, pary wymiarów i DPI, limity boków rastra i pikseli, kotwice oraz współrzędne siatki są walidowane przed dowiązaniem

TXLSXImage.OffsetXEMU i OffsetYEMU zachowują pozycję obrazu wewnątrz jego komórki albo absolutnej kotwicy przez round-tripy XLSX i ODS

TXLSReportDynamicFormat i TXLSReportFormatEvent pozwalają uruchamiaczowi stosować formaty liczb, wysokości wierszy i szerokości kolumn dla każdego celu

Wykonywanie wielokrotnego użytku

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgressi TXLSReportRunProgressEvent opisują granice postępu i anulowania

TXLSCompiledReportRunner udostępnia Run, RunToStream, RunToFile, RunToEncryptedFilei Cancel, przy czym ReportTemplate, State, Progress, OnProgressi OnFormat sterują wykonywaniem wielokrotnego użytku; nieudana walidacja zgłasza EXLSReportData przed deterministycznymi zapisami

ErrorMode (typ TXLSReportErrorMode) ma domyślnie xremStop; xremWriteAndContinue obsługuje tylko jawne błędy EXLSReportRecoverableData i wyniki DataError resolverów, zapisuje uporządkowane, niezmienne problemy w LastResult (jest to IXLSReportRunResult udostępniające State, AppliedCount, IssueCount, indeksowane Issuesoraz FailureClassName / FailureMessage błędu śmiertelnego), którego migawki TXLSReportRuntimeIssue ujawniają swoją Category (typ TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProvideralbo xrricExpression) i raportują TargetIndex, SheetName, Coloraz to, czy problem był już WasWritten do wyjścia, a kończy się stanem xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults pozwala na 100 000 zachowanych problemów, 512 znaków na sanityzowany komunikat i 16 MiB pamięci na problemy; przypisz dodatni własny rekord RuntimeLimits przed uruchomieniem i zostaw RuntimeDiagnosticsSheetName puste, chyba że wymagany jest jeden strukturalny arkusz diagnostyki

Odwracalne wartości i formuły komórek stają się literałem [Report error CODE] message , bezpieczne cele niebędące komórkami zachowują oryginalną wartość, a opcjonalny arkusz diagnostyki oznacza te strukturalne problemy jako zapisane; błędy nazw arkuszy i formuł nazw zdefiniowanych zawsze przerywają działanie, bo potrafią zmienić strukturę skoroszytu

Błędy danych deklarowane przez resolver, dzielenie przez zero w wyrażeniach i nieprawidłowe wyrażenia regularne używają stabilnych kategorii dostawcy albo wyrażenia; rzucane wyjątki resolverów oraz wszystkie błędy callbacków, anulowania, limitów zasobów, rollbacku, serializacji, bezpieczeństwa i strukturalne pozostają śmiertelne

RunToStream, RunToFilei RunToEncryptedFile etapują serializację wewnątrz tego samego czasu życia uruchomienia i sesji danych, po czym publikują raz; każdy błąd śmiertelny, anulowanie, błąd serializacji, częściowy zapis do strumienia albo podmiany celu zachowuje kompletny poprzedni stan docelowy i zwalnia pamięć tymczasową przed powrotem

Niepusty strumień wyjściowy musi być czytelny, zapisywalny, rozszerzalny i przewijalny, żeby rollback mógł przywrócić oryginalne bajty, rozmiar i pozycję; migawki do 8 MiB pozostają w pamięci, a większe korzystają z zarządzanego magazynu tymczasowego — udane zatwierdzenie zostawia strumień na pozycji zero

Nieszyfrowane wyjście używa formatu źródłowego wygenerowanego skoroszytu, więc szablon ODS produkuje strumień albo plik ODS z wymaganymi metadanymi pakietu; wyjście szyfrowane w dół korzysta z zaszyfrowanego kontenera Office

ImageProvider zachowuje oryginalny kontrakt zgodności; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicyi ClearImageDirectiveCell pozwalają uruchamiaczowi, generatorowi, pasmu zakresu albo pasmu tabeli Excela konsumować wprost prekompilowane cele {{#image Key}} ; pominięcie obu dostawców zostawia te komórki dyrektyw bez zmian

AutofitMode (typ TXLSReportAutofitMode) wybiera autofit całego arkusza (xramNone, xramRows, xramColumnsalbo xramBoth) stosowany raz po wykonaniu wszystkich celów, a AutofitAdjustment to dodatkowy zapas (1.0 = brak, 1.1 = wiersze wyższe o 10%)

Cykl życia generowania i źródła szablonów

TXLSReportLifecyclePhase identyfikuje granice odczytu szablonu, generowania skoroszytu i generowania arkusza, a TXLSReportLifecycleOutcome rozróżnia callbacki wpisane, zakończone, anulowane i zakończone błędem

TXLSReportLifecycleContext dostarcza aktywny skoroszyt i arkusz, stabilną tożsamość arkusza, oryginalne i bieżące współrzędne, IXLSReportDataViewtylko do odczytu, liczbę celów i szczegóły pierwszego błędu; każde wpisane zdarzenie „before” otrzymuje sparowane zdarzenie „after”, nawet gdy generowanie zostanie anulowane albo zakończy się błędem

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheeti AfterGenerateSheet obserwują zamrożony zbiór oryginalnych arkuszy; zmiany struktury napędzane callbackami wyzwalają odświeżenie kompilacji bez dodawania nowo utworzonych arkuszy do bieżącego uruchomienia

TXLSReportGenerator przyjmuje skoroszyt, nazwę pliku, strumień należący do wywołującego albo zaszyfrowany plik i dodaje BeforeReadTemplate oraz AfterReadTemplate do zdarzeń generowania; TXLSReportModificationMode wybiera kompatybilną mutację w miejscu albo izolowane generowanie przez atomic-clone. Tylko do odczytu SourceKind (typ TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStreamalbo xrtsEncryptedFile) i TemplateWorkbook raportują skonfigurowane źródło szablonu, a ModificationMode i IncludeResolver są ustawialne przed uruchomieniem

Szablony plikowe i strumieniowe mają domyślnie xrmAtomicClone; przewijalne strumienie wejściowe przywracają pierwotną pozycję, strumienie tylko-do-przodu są konsumowane w ograniczonych blokach, strumienie wywołującego pozostają otwarte, a strumienie lub pliki wyjściowe są podmieniane dopiero po udanym zakończeniu

Planowanie, sprawdzanie i migracja

TXLSReportPaginationPlanner udostępnia plany KeepTogether, SplitRows, MergeSimilari BalanceColumns dla stałych stopek i zrównoważonego wyjścia

TXLSReportTemplateChecker udostępnia Check, CheckBandi CheckTableBand; TXLSReportTemplateMigrator udostępnia MigrateText i MigrateWorkbook dla obsługiwanych starszych form symboli zastępczych

Przykład dla 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;

Przykład dla 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-owy FeatureShowcase i C++Builderowy XlsxFeatureGallery zawierają kompletne, uruchamialne wersje, które weryfikują stan ukończono-z-błędami i liczbę problemów przed zwolnieniem runnera

Zobacz także

• Zaawansowane przepływy pracy skoroszytu
• TXLSXWorkbook
• TXLSPaginationModel