HotXLS: defined names and cross-sheet formulas in Delphi

Twórz, edytuj, sprawdzaj, obliczaj i eksportuj skoroszyty Excel bezpośrednio z kodu Delphi lub C++Builder. HotXLS to natywna biblioteka Object Pascal z kodem źródłowym dla przepływów XLS i XLSX, przeznaczona do narzędzi desktopowych, zadań batch, systemów raportowych i generowania dokumentów po stronie serwera bez automatyzacji Microsoft Excel

Ten artykuł jest przeznaczony dla teams generating analytical workbooks whose formulas must survive sheet movement, template changes, and user edits. Traktuje defined names and cross-sheet formulas jako produkcyjną inżynierię dokumentów, a nie pojedyncze wywołanie komponentu

Praktyczne ryzyko polega na tym, że cross-sheet formulas are fragile when workbook-level names, sheet-level names, external links, and range movement are not governed. Dlatego przepływ wymaga spisanego kontraktu, obserwowalnej diagnostyki i realistycznych plików regresyjnych

Decyzje architektoniczne

Use names as a stable formula interface. workbook-level versus sheet-level name scope / name syntax, collision handling, hidden names, and user-visible names

• workbook-level versus sheet-level name scope
• name syntax, collision handling, hidden names, and user-visible names
• formula references to generated ranges, moved sheets, and external workbooks
• recalculation policy after names or referenced ranges change

Przebieg implementacji

Resolve name scope before writing formulas. Poniższa kolejność zachowuje czytelność przepływu pracy dla zespołów Delphi i C++Builder

1. inventory existing names before adding generated names
2. create stable names for generated ranges before writing dependent formulas
3. qualify sheet-level names deliberately to avoid accidental workbook-level collisions
4. update formulas after sheet insertion, deletion, or movement
5. calculate and inspect formulas before delivering the workbook

Dowody walidacji

Formula evidence for maintainable workbooks. Zachowaj te pola wraz z wynikiem lub rekordem wsparcia

• name, scope, visible state, target reference, and owner profile
• formula text, resolved references, calculation result, and error state
• external-link references and whether they were preserved, updated, or blocked
• name collisions and remediation actions

Names are API surfaces inside the workbook

Defined names create a contract between formulas, templates, and generated data. Managing scope and references deliberately makes workbooks easier to maintain than hard-coded cell addresses scattered across sheets

Uwagi wdrożeniowe dla produkcji

Traktuj HotXLS: defined names and cross-sheet formulas in Delphi jako jawny kontrakt usługi wokół wywołań HotXLS, oddzielając walidację wejścia, zapis skoroszytu, kontrolę wyniku i dowody dla wsparcia

• Ustal źródło danych, zakresy komórek i format wyjściowy przed utworzeniem skoroszytu
• Zapisuj liczbę wierszy, arkusze, ostrzeżenia i ścieżkę wyjściową w możliwym do sprawdzenia logu
• Szczegóły aplikacji zamykaj w testowalnych helperach zamiast w zdarzeniach UI
• Otwórz lub sprawdź zapisany plik przed przekazaniem go do innego systemu lub klienta

Tryby awarii do przećwiczenia

• Udany SaveAs nie dowodzi, że kontrakt biznesowy nadal jest poprawny
• Czcionki, uprawnienia i ustawienia regionalne mogą różnić się między serwerem a maszyną deweloperską
• Logi nie mogą ujawniać haseł, danych klientów ani linków wewnętrznych

Szczegółowy przykład Delphi

Poniższy przykład Delphi pokazuje praktyczną granicę usługi dla tego tematu, z polityką, logowaniem i walidacją w warstwie możliwej do testowania

procedure BuildNamedFormulaWorkbook(const OutputFile: string; const Assumptions: TAssumptionSet);
var
  Wb: TXLSXWorkbook;
  Inputs: IXLSWorksheet;
  Summary: IXLSWorksheet;
begin
  Wb := TXLSXWorkbook.Create;
  try
    Inputs := Wb.Sheets[0];
    Inputs.Name := 'Inputs';
    Summary := AddWorksheet(Wb, 'Summary');

    WriteAssumptionTable(Inputs, Assumptions);
    DefineWorkbookName(Wb, 'TaxRate', 'Inputs!$B$2');
    DefineWorkbookName(Wb, 'DiscountRate', 'Inputs!$B$3');
    Summary.Range['A1'].Value := 'Net revenue';
    Summary.Range['B1'].Value := '=GrossRevenue*(1-DiscountRate)*(1-TaxRate)';

    AssertRequiredNames(Wb, ['TaxRate', 'DiscountRate', 'GrossRevenue']);
    Wb.Calculate;
    AssertFormulaRangeHasValues(Summary, 'B1:B1');
    WriteFormulaDependencyAudit(Wb);

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

Lista produkcyjna

• 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

Dokumentacja produktu

HotXLS Component

Dodatkowe przykłady kodu

var
  Book: IXLSWorkbook;   // interface-counted: do not Free
  Names: IXLSNames;
begin
  Book := TXLSWorkbook.Create;
  // assume a sheet named 'Data' already holds the detail rows
  Names := Book.GetNames;
  Names.Add('TaxRate', '0.08');
  Names.Add('Helper', 'Data!$A$2:$A$100', False);  // False = hidden from the Name Manager

  // XLS formulas go through Value, with the '=' prefix
  Book.Sheets[1].Cells.Item[2, 2].Value := '=SUM(Data!A2:A100)*TaxRate';
  Book.SaveAs('model.xls');
end;

// the calculation engine resolves names and cross-sheet references in-process
V := Book.Calculate('SUM(Data!D2:D100)*TaxRate');
if VarIsNumeric(V) then
  Log('net total checks out: ' + FloatToStr(V));