HotXLS Component: formula calculation and custom functions في Delphi

أنشئ وحرر وافحص واحسب وصدّر مصنفات Excel مباشرة من كود Delphi أو C++Builder. HotXLS مكتبة جداول Object Pascal أصلية مع المصدر لسير عمل XLS وXLSX، ومناسبة لأدوات سطح المكتب والمهام الدفعية وأنظمة التقارير وتوليد المستندات على الخادم دون أتمتة Microsoft Excel.

هذه المقالة موجّهة إلى developers generating workbooks whose calculated results are part of the product output. وهي تتعامل مع formula calculation and custom functions كجزء من هندسة المستندات في بيئة الإنتاج، لا كاستدعاء سريع لمكوّن.

الخطر العملي هو أن formula results can appear correct in simple cases while dependency order, custom functions, locale parsing, volatile functions, or error values differ in production. لذلك يحتاج المسار إلى عقد واضح وتشخيص قابل للملاحظة وملفات اختبار واقعية.

قرارات البنية

Treat calculation as a deterministic service. calculation mode, dependency refresh, and whether cached values are trusted / custom function names, argument types, null handling, and versioning

• calculation mode, dependency refresh, and whether cached values are trusted
• custom function names, argument types, null handling, and versioning
• locale handling for decimal separators, date literals, and function names
• error-value policy for invalid references, division by zero, and unsupported formulas

مسار التنفيذ

Register custom functions before loading dependent formulas. The order below keeps the workflow reviewable for Delphi and C++Builder teams.

1. register custom functions and workbook names before calculation
2. load or generate formulas with explicit dependency expectations
3. calculate targeted ranges or full workbook output according to the profile
4. compare critical results with independent fixtures or approved Excel output
5. write calculation diagnostics into the support bundle when results are disputed

أدلة التحقق

Calculation evidence for finance and support. Keep these fields with the output or support record.

• formula count, dependency graph summary, custom function calls, and recalculation time
• critical cell addresses, formula text, cached value, calculated value, and error state
• custom function version, arguments, returned value, and exception mapping
• locale profile and unsupported-formula warnings

Custom functions need versioned behavior

A formula engine workflow should make dependencies, custom function registration, recalculation mode, cached results, and error handling visible. That is especially important when generated workbooks are consumed without Excel automation.

ملاحظات تنفيذ للإنتاج

اجعل موضوع «HotXLS Component: formula calculation and custom functions في Delphi» عقد خدمة واضحا حول استدعاءات HotXLS، مع فصل التحقق من الإدخال وكتابة المصنف وفحص الخرج وأدلة الدعم

• حدد مصدر البيانات ونطاقات الخلايا وتنسيق الخرج قبل إنشاء المصنف
• سجل عدد الصفوف والأوراق والتحذيرات ومسار الخرج في سجل دعم قابل للمراجعة
• ضع التفاصيل الخاصة بالتطبيق داخل دوال مساعدة قابلة للاختبار بدلا من نشرها داخل حدث واجهة
• افتح أو افحص الملف المحفوظ قبل تسليمه إلى نظام آخر أو إلى العميل

حالات فشل يجب اختبارها

• نجاح SaveAs لا يثبت أن العقد التجاري بقي صحيحا
• قد تختلف الخطوط والأذونات والإعدادات الإقليمية بين الخادم وجهاز التطوير
• يجب ألا تكشف السجلات كلمات مرور أو بيانات عملاء أو روابط داخلية

مثال Delphi تفصيلي

يوضح المثال التالي حدود خدمة عملية لهذا الموضوع، مع إبقاء السياسات والسجلات والتحقق في طبقة يمكن اختبارها

procedure RecalculateInvoiceWorkbook(const TemplateFile, OutputFile: string; const Orders: TArray<TOrderRow>);
var
  Wb: TXLSXWorkbook;
  Sh: IXLSWorksheet;
  RowIndex: Integer;
  Order: TOrderRow;
begin
  Wb := TXLSXWorkbook.Create;
  try
    Wb.Open(TemplateFile);
    RegisterInvoiceFunctions(Wb);
    Sh := Wb.Sheets[0];
    EnsureTemplateVersion(Wb, 'invoice-formulas-v3');

    RowIndex := 2;
    for Order in Orders do
    begin
      Sh.Range['A' + IntToStr(RowIndex)].Value := Order.Sku;
      Sh.Range['B' + IntToStr(RowIndex)].Value := Order.Quantity;
      Sh.Range['C' + IntToStr(RowIndex)].Value := Order.UnitPrice;
      Sh.Range['D' + IntToStr(RowIndex)].Value := '=B' + IntToStr(RowIndex) + '*C' + IntToStr(RowIndex);
      Sh.Range['E' + IntToStr(RowIndex)].Value := '=InvoiceTax(D' + IntToStr(RowIndex) + ')';
      Inc(RowIndex);
    end;

    Wb.Calculate;
    AssertFormulaRangeHasValues(Sh, 'D2:E' + IntToStr(RowIndex - 1));
    WriteCalculationAudit(Wb, 'invoice-formulas', RowIndex - 2);

    if Wb.SaveAs(OutputFile) <> 1 then
      RaiseWorkbookSaveError(OutputFile);
  finally
    Wb.Free;
  end;
end;

قائمة فحص الإنتاج

• Run the workflow on an empty workbook, a normal customer workbook, and a worst-case workbook
• Open the output with the target spreadsheet application or downstream importer
• Log product version, template version, profile, row count, output path, elapsed time, and warning count
• Keep passwords, temporary files, customer data, and support bundles under explicit retention rules
• Add regression workbooks when a customer file exposes a new edge case

Product documentation

HotXLS Component