واجهة برمجة التقارير المُجمَّعة

تجمّع وحدة 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

العلاقات ومدمِجات الجداول الكسولة

يحتفظ 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 اللاحقة

يجعل FixedBand مناطق الصفوف تطمس الصفوف أسفل القالب بدلًا من إدراج صفوف جديدة، فيبقى المحتوى المحيط في موضع ثابت

تستنسخ مناطق نطاقات الصفوف والأعمدة محادثاتِ التعليقات المترابطة عندما ينتمي كل جذر وردٍّ إلى نطاق القالب؛ وتُقيَّم العناصر النائبة للنص واسم العرض لكل سجل، وتستلم التعليقات المنسوخة معرفات جديدة ومعرفات آباء معاد تعيينها، وتُعاد استخدام سجلات الأشخاص القائمة في المصنف

ترفض الترجمة المحادثاتَ المقسمة عبر حد القالب والآباء المفقودين والمعرفات المكررة ومراسي الخلايا غير الصالحة قبل التوسيع؛ ويُفحص فيض المرساة قبل تعديل ورقة العمل، ويزيل التشغيلُ الفاشل أو الملغى المحادثاتِ المولدة مع استعادة حالة القالب

يوسّع 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 كائن TXLSReportImageRequest يحمل هوية ورقة عمل مستقرة وهدفًا مجمَّعًا وأسماء منطقة وجدول وصفوفًا منطقية ومؤشرية وعرضًا للقراءة فقط للصف الحالي وخلايا التوجيه والتثبيت وأبعاد الهدف وإزاحاته بوحدات 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 ميبيبايت، وتُتحقق تواقيع الحمولة ورؤوس الهندسة وأزواج الأبعاد و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 ميبيبايت من ذاكرة المشكلات؛ أسند سجل RuntimeLimits مخصصًا موجبًا قبل التشغيل، واترك RuntimeDiagnosticsSheetName فارغًا ما لم تكن ورقة تشخيصات بنيوية واحدة مطلوبة

تصبح قيم الخلايا وصيغها القابلة للاسترداد نصًّا حرفيًّا بالشكل [Report error CODE] message، وتحتفظ الأهداف غير الخلوية الآمنة بقيمتها الأصلية، وتعلّم ورقة تشخيصات اختيارية تلك المشكلات البنيوية كمكتوبة؛ وتوقف حالات فشل أسماء أوراق العمل وصيغ الأسماء المعرَّفة التشغيل دائمًا لأنها قد تغيّر بنية المصنف

تستخدم أخطاء البيانات المعلنة من المحلِّلات وقسمة التعبير على صفر والتعبيرات النمطية غير الصالحة فئات مزوّد أو تعبير مستقرة؛ وتبقى استثناءات المحلِّلات المرمية وجميع حالات فشل معاودة الاتصال والإلغاء وحدود الموارد والتراجع والتسلسل والأمان والبنية قاتلة

تنظّم RunToStream وRunToFile وRunToEncryptedFile عملية التسلسل داخل عمر التشغيل وجلسة البيانات نفسيهما ثم تنشر مرة واحدة؛ أي فشل قاتل أو إلغاء أو تسلسل أو كتابة جزئية للدفق أو استبدال وجهة يحافظ على الوجهة السابقة كاملة ويحرر التخزين المؤقت قبل العودة

يجب أن يكون دفق الإخراج غير الفارغ قابلًا للقراءة والكتابة وتغيير الحجم والبحث كي يستطيع التراجع استعادة بايتاته الأصلية وحجمه وموضعه؛ تبقى اللقطات حتى 8 ميبيبايت في الذاكرة وتستخدم اللقطات الأكبر تخزينًا مؤقتًا مُدارًا، بينما يترك الإثبات الناجح الدفق عند الموضع صفر

يستخدم الإخراج غير المشفَّر صيغة مصدر المصنف المولَّد، فينتج قالب 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 للقراءة فقط وعدد الأهداف وتفاصيل أول فشل؛ ويستقبل كل حدث "قبل" داخلاً حدث "بعد" مقترنًا حتى عند إلغاء التوليد أو فشله

تراقب 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 لأشكال العناصر النائبة القديمة المدعومة

مثال 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;

يحتوي العرض التوضيحي FeatureShowCase بلغة Delphi ومعرض XlsxFeatureGallery بلغة C++Builder على نسخ كاملة قابلة للتشغيل تتحقق من حالة الاكتمال مع أخطاء وعدد المشكلات قبل تحرير المشغِّل

انظر أيضًا

• سير عمل المصنف المتقدم
• TXLSXWorkbook
• TXLSPaginationModel