API การรายงานแบบคอมไพล์

ยูนิต lxReport คอมไพล์ตัวยึดตำแหน่งและแถบรายงานเชิงโครงสร้างเพียงครั้งเดียว จากนั้นนำข้อมูลที่เป็นของตัวเรียกใช้ไปใช้ผ่านเคอร์เซอร์แบบมีขอบเขต โดยไม่ต้องสแกนออบเจกต์สมุดงานที่สร้างขึ้นซ้ำ

สัญญาตารางและเคอร์เซอร์

ตัวให้บริการคิวรีที่ควบคุมได้

IXLSReportQueryExecutor.ExecuteReadOnly ทำให้การดำเนินการคิวรีเป็นของโฮสต์และยอมรับเฉพาะนิยามที่ลงทะเบียนโดยโค้ดแอปพลิเคชัน

TXLSReportQueryParameter, TXLSReportQueryParameters และ TXLSReportQueryDefinition เปิดเผย Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameter และ ClearParameters

TXLSReportQueryProvider ใช้ RegisterQuery, RemoveQuery, Clear และ TryGetTable โดยมี Count, Definitions และ MaximumTimeoutMS เปิดเผยรายการที่อนุญาตและเพดานหมดเวลา

Data session รายรอบการรัน

IXLSReportDataSession คือ lazy cache แบบแยกโดดที่อยู่หลังการรันรายงานหนึ่งรอบ: DeclareRequest ลงทะเบียน TXLSReportDataRequest (ชนิด TXLSReportDataRequestKind: xrdrkNamed หรือ xrdrkUser) ที่มี TXLSReportDataSource (ชนิด TXLSReportDataSourceKind: ไม่ระบุ, cell, range band, table band หรือ expression) และรายการ TXLSReportDataParameter อธิบายแหล่งข้อมูลกับค่าของมัน ส่วน RunControl เป็น handle สำหรับยกเลิก IXLSReportRunControl ของโฮสต์; HasResolver ตรวจ provider key, TryGetTable กับ RequireTable อ่าน alias ที่แคชไว้, TryResolveTable กับ RequireResolvedTable resolve ตามต้องการแล้วคืน TXLSReportDataResolveResult (สถานะ TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFound หรือ xrdrsDataError) และ TryGetState รายงาน TXLSReportDataSessionState เป็น loading, resolved, not found หรือ data error โดย CachedAliasCount กับ ResolvedAliasCount บอกขนาดของ session

IXLSReportDataView.TryGetValue ค้นค่าที่ระบุชื่อโดยไม่ raise ช่วยเติม accessor แบบดัชนี Count, Names และ Values

ความสัมพันธ์และคอมบิเนเตอร์ตารางแบบขี้เกียจ

TXLSReportRowIndexes และ TXLSReportRelationIndex เก็บหมายเลขแถวลูกไว้ในบัคเก็ตคีย์แบบผสม; ใช้ FindChildRows หรือ CreateChildCursor และตรวจสอบ BucketCount หรือ IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregate และ TXLSReportJoinKind กำหนดค่า TXLSReportTableFactory

แถบช่วงที่มีชื่อและช่วงชัดเจน

TXLSReportBandKind เลือกการขยายแถว, คอลัมน์ หรือ cross-tab และ TXLSReportBandState รายงานสถานะวงจรชีวิต

TXLSCompiledReportBand ยอมรับชื่อที่กำหนดแบบขอบเขตที่แน่นอนหรือ CreateForRange จากนั้นขยายผ่านโอเวอร์โหลด Run; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCount และ State เปิดเผยแผนการคอมไพล์

TXLSCompiledTableReportBand.Run ขยายแถวเทมเพลตข้อมูลตาราง Excel หนึ่งแถวในขณะที่รักษาข้อมูลเมตาของตาราง; ตรวจสอบ TableName, Sheet, SheetIndex, ExcelTable, TemplateRow และ State

TXLSCompiledSheetReportBand.Run สร้างแผ่นงานต่อเรกคอร์ดโดยใช้ NameColumn, NamePrefix และ DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run สร้างแผ่นงานต่อเนื่องโดยใช้ NamePrefix และ DeleteTemplateAfterRun

เทมเพลตทั้งสมุดงาน

TXLSReportTemplateTarget และ TXLSReportTemplateTargets เลือกเซลล์, หมายเหตุ, ไฮเปอร์ลิงก์, รูปร่าง, ส่วนหัวและท้ายกระดาษ, ชื่อแผ่นงาน, ชื่อที่กำหนด และคุณสมบัติเอกสาร

TXLSCompiledReportTemplate.Compile จับเป้าหมายและนิพจน์, Analyze คืน TXLSReportIssues ที่มีที่อยู่, โอเวอร์โหลด Run ใช้ค่า และ WriteDiagnostics เขียนปัญหาไปยังแผ่นงาน; TargetAreas, TargetCount และ UserTableCount อธิบายพื้นผิวที่คอมไพล์และ user table ที่ลงทะเบียนไว้

ProcessStructuralDirectives (ค่าเริ่มต้น True) ให้ Run ของเทมเพลต execute directive เชิงโครงสร้าง {{#delete}} และ {{#format}} หลังจากใส่ค่าเป้าหมายครบ — โดย TXLSReportDirectiveProcessor เบื้องหลังจะ parse ช่วง, ใช้งาน และรายงานจำนวนที่จัดการผ่าน 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 อัปเดต directive รูปภาพที่ระบุตำแหน่งแน่นอน

TXLSReportImageBinder.ApplyTargetV2 ผูกเซลล์ directive หนึ่งเซลล์ผ่านสัญญา provider แบบ V2 และส่งต่อ TXLSReportTransformImageEvent ที่แก้ payload ที่ resolve แล้วได้ก่อนลงเวิร์กบุ๊กจริง ตัว placeholder ที่ resolve แล้วเองก็เป็น TXLSReportEvaluatedTarget ที่ TXLSReportEvaluatedTargetKind แยกแยะระหว่าง xretNone, xretText, xretValue และ xretFormula; IXLSReportImageCancellation.IsCancellationRequested ให้ provider ที่ทำงานนานเห็นการยกเลิกแบบ cooperative

IXLSReportImageDataProviderV2.GetImage รับ TXLSReportImageRequest ที่มีตัวตนแผ่นงานแบบเสถียร, เป้าหมายที่คอมไพล์แล้ว, ชื่อ band และตาราง, แถวเชิงตรรกะกับแถวเคอร์เซอร์, มุมมองแถวปัจจุบันแบบอ่านอย่างเดียว, เซลล์ directive และ anchor, ขนาดเป้าหมายกับ offset หน่วย EMU และ IXLSReportImageCancellation

TXLSReportImageResult บรรทุก TXLSReportImagePayload ที่ Kind (TXLSReportImagePayloadKind) เลือกได้ทั้ง xripMissing, bytes หรือ stream โดยอายุของ stream ถูกกำหนดด้วย TXLSReportImageStreamOwnership: stream แบบ xrisoBorrowed ยังเป็นของผู้เรียกและคืนตำแหน่งเดิมถ้า seek ได้ ส่วนแบบ xrisoTransferred จะถูกปล่อยให้ครั้งเดียวจบ; SourceWidth, SourceHeight, SourceDpiX และ SourceDpiY ที่ใส่ได้ (ไม่บังคับ) ใช้ยืนยันหรือแทนที่ขนาดจริงของต้นทาง

xrifNatural ใช้ขนาดจริงของต้นทาง, xrifContain ย่อ/ขยายให้พอดีกล่องเป้าหมาย, xrifCover เต็มกล่องโดย crop ต้นทางแบบสมมาตร และ xrifStretch เต็มกล่องโดยไม่รักษาสัดส่วนภาพ; รูปทรงของ PNG, JPEG, GIF, BMP, EMF และ WMF อ่านจาก header ที่จำกัดขอบเขตโดยไม่ต้อง decode พิกเซล

OnTransformImage รันหลังจาก snapshot ข้อมูลจาก provider แล้วแต่ก่อนแก้แผ่นงาน; MaximumImageBytes ค่าเริ่มต้น 64 MiB และลายเซ็น payload, geometry header, คู่มิติกับ DPI, ขีดจำกัดด้านราสเตอร์และพิกเซล, anchor และพิกัดกริด จะถูกตรวจก่อนผูกภาพทุกครั้ง

TXLSXImage.OffsetXEMU และ OffsetYEMU เก็บตำแหน่งของภาพภายในเซลล์หรือ absolute anchor เดิมไว้ได้ข้ามการ round trip ระหว่าง XLSX และ ODS

TXLSReportDynamicFormat และ TXLSReportFormatEvent ให้ตัวรันใช้รูปแบบตัวเลข, ความสูงแถว และความกว้างคอลัมน์ต่อเป้าหมาย

การดำเนินการที่นำกลับมาใช้ใหม่ได้

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgress และ TXLSReportRunProgressEvent อธิบายขอบเขตความคืบหน้าและการยกเลิก

TXLSCompiledReportRunner เปิดเผย Run, RunToStream, RunToFile, RunToEncryptedFile และ Cancel โดยมี ReportTemplate, State, Progress, OnProgress และ OnFormat ควบคุมการดำเนินการที่นำกลับมาใช้ใหม่ ถ้าตรวจสอบไม่ผ่านจะ raise EXLSReportData ก่อนการเขียนที่กำหนดแน่นอน

ErrorMode (ชนิด TXLSReportErrorMode) ค่าเริ่มต้นเป็น xremStop; xremWriteAndContinue จัดการเฉพาะความล้มเหลวแบบ EXLSReportRecoverableData ที่ระบุชัดและผล DataError จาก resolver โดยเก็บปัญหาแบบ immutable ตามลำดับไว้ใน LastResult (ซึ่งเป็น IXLSReportRunResult เปิดเผย State, AppliedCount, IssueCount, Issues แบบเข้าถึงด้วยดัชนี และ FailureClassName / FailureMessage ของความล้มเหลวร้ายแรง) โดย snapshot TXLSReportRuntimeIssue เปิดเผย Category (เป็น TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProvider หรือ xrricExpression) พร้อมรายงาน TargetIndex, SheetName, Col และว่าปัญหาถูกเขียนลงเอาต์พุตไปแล้วหรือยังผ่าน WasWritten แล้วรอบรันจบเป็น xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults ยอมให้เก็บปัญหาได้ 100,000 รายการ, ข้อความที่ทำความสะอาดแล้วยาวได้ 512 ตัวอักษร และหน่วยความจำสำหรับปัญหา 16 MiB; กำหนด record RuntimeLimits แบบกำหนดเองที่เป็นบวกก่อนรัน และปล่อย RuntimeDiagnosticsSheetName ว่างไว้เว้นแต่ต้องการแผ่นงานวินิจฉัยแบบมีโครงสร้างหนึ่งแผ่น

ค่าและสูตรของเซลล์ที่กู้คืนได้จะกลายเป็นข้อความ [Report error CODE] message ตรง ๆ, เป้าหมายที่ไม่ใช่เซลล์ที่ปลอดภัยจะคงค่าเดิม และแผ่นงานวินิจฉัย (ถ้าเปิดใช้) จะมาร์คปัญหาเชิงโครงสร้างเหล่านี้ว่าเขียนแล้ว; ความล้มเหลวของชื่อแผ่นงานและสูตร defined name จะหยุดเสมอ เพราะกระทบโครงสร้างสมุดงาน

Data error ที่ resolver ประกาศ, การหารศูนย์ในนิพจน์ และ regex ที่ไม่ถูกต้อง จะใช้หมวด provider หรือ expression ที่เสถียร; ส่วน exception ที่ resolver throw และความล้มเหลวอื่นทั้งหมด ไม่ว่า callback, การยกเลิก, ขีดจำกัดทรัพยากร, rollback, serialization, ความปลอดภัย หรือเชิงโครงสร้าง ยังถือเป็น fatal

RunToStream, RunToFile และ RunToEncryptedFile จัด serialization ไว้ในอายุ run และ data session เดียวกันแล้ว publish ทีเดียว; ความล้มเหลวใด ๆ ทั้ง fatal, ถูกยกเลิก, serialization, เขียน stream ไม่ครบ หรือแทนที่ปลายทางไม่สำเร็จ จะรักษาปลายทางเดิมไว้ครบถ้วนและคืนพื้นที่ชั่วคราวก่อน return

output stream ที่ไม่ว่างต้องอ่าน เขียน ปรับขนาด และ seek ได้ เพื่อให้ rollback คืนไบต์ ขนาด และตำแหน่งเดิมได้; snapshot ไม่เกิน 8 MiB จะอยู่ในหน่วยความจำ ที่ใหญ่กว่านั้นใช้พื้นที่ชั่วคราวแบบมีผู้จัดการ ส่วน commit สำเร็จจะปล่อย stream ไว้ที่ตำแหน่งศูนย์

เอาต์พุตแบบไม่เข้ารหัสใช้รูปแบบต้นทางของสมุดงานที่สร้าง เช่น เทมเพลต ODS จะได้ stream หรือไฟล์ ODS พร้อม package metadata ที่จำเป็น; ส่วนเอาต์พุตแบบเข้ารหัสยังใช้คอนเทนเนอร์ Office แบบเข้ารหัสเหมือนเดิม

ImageProvider ยังคงสัญญาความเข้ากันได้เดิมไว้; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicy และ ClearImageDirectiveCell ให้ runner, generator, range band หรือ Excel-table band ใช้เป้าหมาย {{#image Key}} ที่คอมไพล์ล่วงหน้าได้โดยตรง ถ้าไม่ตั้ง provider ทั้งสองแบบ เซลล์ directive เหล่านี้จะถูกปล่อยไว้ตามเดิม

AutofitMode (ชนิด TXLSReportAutofitMode) เลือก autofit ทั้งแผ่นงาน (xramNone, xramRows, xramColumns หรือ xramBoth) โดยทำครั้งเดียวหลังเป้าหมายทุกตัวรันจบ และ AutofitAdjustment เป็นตัวคูณเผื่อพื้นที่ส่วนเกิน (1.0 = ไม่เผื่อ, 1.1 = แถวสูงขึ้น 10%)

วงจรชีวิตการสร้างและแหล่งเทมเพลต

TXLSReportLifecyclePhase ระบุขอบเขตการอ่านเทมเพลต, การสร้างสมุดงาน และการสร้างแผ่นงาน ส่วน TXLSReportLifecycleOutcome แยก callback ออกเป็นเข้าสู่ขั้น, สำเร็จ, ถูกยกเลิก และล้มเหลว

TXLSReportLifecycleContext จัดให้ทั้งสมุดงานและแผ่นงานที่กำลังทำงาน, ตัวตนแผ่นงานแบบเสถียร, พิกัดเดิมกับพิกัดปัจจุบัน, IXLSReportDataView แบบอ่านอย่างเดียว, จำนวนเป้าหมาย และรายละเอียดความล้มเหลวแรก; before event ทุกตัวที่เข้าสู่ขั้นจะได้ after event คู่กลับมาเสมอ แม้การสร้างจะถูกยกเลิกหรือล้มเหลว

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheet และ AfterGenerateSheet มองเห็นชุดแผ่นงานต้นฉบับแบบ frozen ถ้า callback แก้โครงสร้างจะ trigger การ refresh การคอมไพล์ แต่แผ่นงานที่สร้างใหม่จะไม่ถูกเพิ่มเข้า run ปัจจุบัน

TXLSReportGenerator รับทั้งสมุดงาน, ชื่อไฟล์, stream ที่ผู้เรียกเป็นเจ้าของ หรือไฟล์แบบเข้ารหัส และเพิ่ม BeforeReadTemplate กับ AfterReadTemplate เข้าไปใน generation events; TXLSReportModificationMode เลือกได้ระหว่างแก้ของเดิมในที่แบบเข้ากันได้ กับสร้างจาก atomic clone แบบแยกโดด SourceKind แบบอ่านอย่างเดียว (ชนิด TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStream หรือ xrtsEncryptedFile) กับ TemplateWorkbook รายงานแหล่งเทมเพลตที่ตั้งไว้ ส่วน ModificationMode และ IncludeResolver ตั้งค่าก่อนรันได้

เทมเพลตจากไฟล์และ stream ใช้ xrmAtomicClone เป็นค่าเริ่มต้น; input stream ที่ seek ได้จะคืนตำแหน่งเดิม, stream แบบ forward-only จะถูกอ่านเป็นบล็อกจำกัดขนาด, stream ของผู้เรียกจะไม่ถูกปิด และ output stream หรือไฟล์จะถูกแทนที่หลังสำเร็จเท่านั้น

การวางแผน, การตรวจสอบ และการย้ายข้อมูล

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 มีเวอร์ชันสมบูรณ์ที่รันได้ ซึ่งตรวจสถานะ completed-with-errors และจำนวนปัญหาก่อนปล่อย runner คืน

ดูเพิ่มเติม

• เวิร์กโฟลว์สมุดงานขั้นสูง
• TXLSXWorkbook
• TXLSPaginationModel