Dokumentácia HotXLS

Prehľad

HotXLS Logo
HotXLS Excel Read/Write Library je vysokovýkonná komponenta na čítanie a zápis Excel súborov pre Delphi & C++Builder Umožňuje vytvárať nové tabuľky Excel a čítať alebo upravovať existujúce zošity XLS a XLSX bez nutnosti inštalácie Microsoft Excel alebo Office na počítači
HotXLS je napísaný výhradne v Object Pascal. Číta a zapisuje súbory Excel priamo na binárnej úrovni a úrovni OOXML, takže nevzniká réžia COM/OLE automatizácie a nie je potrebná závislosť na licencovanom alebo prítomnom Office. HotXLS podporuje Delphi a C++Builder XE5 až 13 Florence
Klasické farebné formátovanie XLS zostáva zámerne založené na palete farieb. Pozrite si Klasický farebný model XLS pre rozhodnutie ohľadom ThemeColor / TintAndShade

Architektúra duálneho rozhrania

HotXLS poskytuje dve súbežne existujúce fasádne jednotky, vďaka čomu môžu starší kód XLS a nový kód XLSX existovať vedľa seba bez akéhokoľvek refaktorovania:
lxHandle Primárne rozhranie pre formát Excel 97–2003 BIFF8 (.xls), plus export do HTML, RTF, CSV a TSV Všetok existujúci kód používateľa naďalej využíva túto jednotku bez zmien. Vstupné body: TXLSWorkbook, TXLSWorksheet, IXLSWorkbook, IXLSRange
lxHandleX Primárne rozhranie pre formát Excel 2007+ OOXML (.xlsx) a tabuľkový dokument OpenDocument (.ods) na čítanie a zápis. Poskytuje vlastné typy zošitov a pracovných hárkov, takže správanie špecifické pre XLSX nie je spätne zabudované do kódovej cesty BIFF. Vstupné body: TXLSXWorkbook, TXLSXWorksheet, TXLSXCell
Obe fasády zdieľajú rovnaký formulový engine, rovnakú vrstvu podpory Unicode a rovnaký exportný kanál Pozrite si Prehľad fasády XLSX pre úplnú hierarchiu tried sprístupnenú cez lxHandleX

Rýchly štart

Nasledujúce ukážky zobrazujú minimálny kód na vytvorenie zošita s jedným pracovným hárkom a zápis hodnoty do bunky.

Klasické XLS (lxHandle)

uses lxHandle;

var
  Book: IXLSWorkbook;
  ws:   TXLSWorksheet;
begin
  Book := TXLSWorkbook.Create;
  // Pridanie pracovného hárka a priradenie názvu
  ws := Book.Sheets.Add;
  ws.Name := 'Sheet1';

  // Zápis hodnôt do buniek pomocou notácie A1
  ws.Range['A1'].Value := 'Hello';
  ws.Range['B1'].Value := 42;
  ws.Range['C1'].Formula := '=B1*2';

  // Použitie základného formátovania
  ws.Range['A1'].Font.Bold := True;
  ws.Range['A1'].Interior.Color := clYellow;

  Book.SaveAs('output.xls');
end;

XLSX (lxHandleX)

uses lxHandleX;

var
  Book: TXLSXWorkbook;
  ws:   TXLSXWorksheet;
  cell: TXLSXCell;
begin
  Book := TXLSXWorkbook.Create;
  try
    ws := Book.Sheets.Add('Sheet1');

    // Zápis reťazcovej a číselnej hodnoty
    ws.Cells[1, 1].Value := 'Product';
    ws.Cells[1, 2].Value := 'Price';
    ws.Cells[2, 1].Value := 'Widget';
    ws.Cells[2, 2].Value := 9.99;

    // Použitie formátu čísla pre menu
    cell := ws.Cells[2, 2];
    cell.NumberFormat := '$#,##0.00';

    Book.SaveAs('output.xlsx');
  finally
    Book.Free;
  end;
end;
Pre rozsiahlejší návod pokrývajúci obe fasády v jednom demonštračnom projekte si pozrite Demonštráciu prehliadky API

Funkcie

Súborové I/O a podpora prúdov

Čítanie existujúcich súborov Excel, zápis nových alebo existujúcich súborov Excel, spracovanie ochrany heslom klasického XLS a šifrovaného uloženia XLSX, a rýchly výpis názvov hárkov zo súborov alebo prúdov XLS a XLSX bez načítania celého zošita. Otvorenie CSV ako zošita je podporované cez IXLSWorkbook.OpenCSV

Hodnoty buniek a vzorce

Čítanie a zápis hodnôt buniek všetkých natívnych typov Excel: číslo, reťazec, dátum/čas, boolovská hodnota a vzorec Vstavaný výpočtový engine vyhodnocuje vzorce v klasických zošitoch XLS aj XLSX s podporou:
  • Textových funkcií (LEFT, MID, TRIM, SUBSTITUTE, …)
  • Dátumových a pracovných funkcií (DATE, NETWORKDAYS, WORKDAY, …)
  • Inžinierskych a konverzných funkcií číselných sústav (BIN2DEC, HEX2DEC, …)
  • Bitových funkcií (BITAND, BITOR, BITXOR, …)
  • Štatistických a agregačných funkcií (AVERAGE, SUMIF, COUNTIFS, …)
  • Matematických funkcií (ROUND, MOD, POWER, …)
Spätné volanie OnUserFunction umožňuje spracovanie vlastných alebo nepodporovaných funkcií pracovného hárka za behu Pozrite si Spätné volanie OnUserFunction pre signatúru a príklady
Príklad vyhodnotenia vzorca

Formátovanie buniek

Plný prístup k atribútom vzhľadu bunky:
  • Písma — názov, veľkosť, farba (RGB alebo farba témy + odtieň), tučné, kurzíva, podčiarknutie, prečiarknutie, horný index, dolný index, tieň a obrys
  • Zarovnanie — horizontálne a vertikálne zarovnanie, orientácia textu (uhol), úroveň odsadenia, zalamovanie textu, zmenšenie na mieru a poradie čítania (RTL/LTR)
  • Ohraničenia — všetky štyri hrany a uhlopriečky, štýl čiary, hrúbka a farba RGB / témy
  • Výplň — plná výplň, vzorované výplne, farby popredia a pozadia vrátane farby témy s TintAndShade
  • Číselné formáty — vstavaný a vlastný formátovací reťazec pre dátum, čas, menu, percentá a vedecký zápis
  • Komentáre / anotácie — pridávanie, čítanie a štýlovanie komentárov buniek

Operácie s rozsahmi

IXLSRange (klasická fasáda) a TXLSXRange (fasáda XLSX) poskytujú bohatú sadu operácií s rozsahmi:
  • Zlučovanie a oddeľovanie buniek; prístup k zlúčenej oblasti ľubovoľnej bunky
  • Kopírovanie, presúvanie, vkladanie a odstraňovanie rozsahov s riadením smeru posunu
  • Zoskupovanie a rozoskupovanie riadkov alebo stĺpcov pre zobrazenie osnovy/zbalenia
  • Automatické prispôsobenie výšky riadka a šírky stĺpca obsahu buniek
  • Použitie vstavaných pomenovaných štýlov buniek (ApplyBuiltinStyle)
  • Výbery viacerých oblastí (TXLSWorksheet.SelectAreas)
  • Spätné volanie iterácie ForEachCell na dávkové spracovanie buniek

Funkcie pracovného hárka

Riadenie na úrovni pracovného hárka zahŕňa:
  • Názov hárka, farba záložky, viditeľnosť (skrytý / veľmi skrytý) a navigácia podľa indexu
  • Ochrana hárka s granularitou podľa oprávnenia; ochrana na úrovni zošita
  • Zmrazenie tabúľ, rozdelenie tabúľ a pozícia posúvania
  • Rozsahy automatického filtra s kritériami; pravidlá overenia údajov zoznamu
  • Podmienené formátovanie: farebné škály (2 a 3 farby), dátové pruhy a sady ikon
  • Hľadanie textu a nahradenie textu v rámci pracovného hárka
  • Možnosti zobrazenia: farba mriežky, režim zobrazenia vzorca, zobrazenie núl, zobrazenie nadpisov, zobrazenie sprava doľava, zobrazenie symbolov osnovy a úroveň priblíženia
  • Štruktúrované tabuľky (TXLSTable / TXLSXTable): pridávanie, prístup a štýlovanie tabuliek Excel s riadkami hlavičiek a striedajúcimi sa riadkami
  • Grafy: pridávanie hárkov grafov a vložených grafov cez TXLSWorksheetsAddChartSheet a TXLSXChart

Hypertextové odkazy a pomenované rozsahy

Pridávanie a čítanie hypertextových odkazov (URL, mailto a odkazy na bunky v rámci zošita) cez IXLSHyperLinks. Definovanie a rozlišovanie pomenovaných rozsahov na úrovni zošita a pracovného hárka cez IXLSNames / TXLSXDefinedNames. Pomenované rozsahy je možné použiť vo vzorcoch a rozlíšiť späť na rozsah buniek cez RefersToRange

Obrázky a tvary

Vkladanie rastrových obrázkov (BMP, JPG, PNG, GIF) do pracovných hárkov cez TXLSShapes.AddPicture / TXLSXWorksheet.AddImage. Vytváranie samostatných textových polí v klasickom XLS cez TXLSShapes.AddTextBox. Zachovanie pravidiel konektorov a solvera OfficeArt vytvorených v Exceli v kresbách BIFF8 a sprístupnenie možností surového tvaru FOPT cez TXLSShape.OfficeArtOptions pre pokročilé pracovné postupy kreslenia

Nastavenie strany a tlač

Plný prístup k rozloženiu tlače cez IXLSPageSetup:
  • Veľkosť papiera (A4, Letter, Legal a mnohé ďalšie; pozrite si PaperSize)
  • Orientácia (na výšku / na šírku), okraje, centrovanie horizontálne / vertikálne
  • Reťazce hlavičky a päty s formátovacími kódmi Excel (tučné, kurzíva, číslo strany, dátum atď.; pozrite si Formátovacie kódy hlavičky/päty)
  • Ručné horizontálne a vertikálne zlomy strán
  • Prispôsobenie na počet strán; percento priblíženia; oblasť tlače; titulky tlače (opakovanie riadkov / stĺpcov)
  • Koncept; čiernobielo; tlač mriežky; tlač nadpisov; tlač poznámok

Formáty exportu

Export celých zošitov, jednotlivých pracovných hárkov alebo ľubovoľných rozsahov buniek do:
  • HTML — úplný dokument alebo vnorený fragment tabuľky pre pracovné postupy náhľadu alebo e-mailu; ovládateľné cez TXLSHTMLExport a TXLSXHtmlExportOptions
  • RTF — formátovaný text na import do textového procesora
  • CSV — hodnoty oddelené čiarkou s konfigurovateľným oddeľovačom a kódovaním
  • TSV — hodnoty oddelené tabulátorom
  • ODS — tabuľkový dokument OpenDocument cez fasádu lxHandleX

Export databázy a mriežky

Export akéhokoľvek datasetu kompatibilného s TDataSet alebo TDBGrid priamo do Excel, HTML alebo RTF pomocou komponentov TDataToXLS alebo TGridToXLS Oba komponenty spúšťajú udalosti AfterCell, AfterRow, AfterTitle a AfterGroup pre jemnozrnnú kontrolu výstupu a podporujú viacúrovňové zoskupovacie polia

Zachovanie projektu VBA

HotXLS zachováva obsah projektu VBA pri spracovávaní zošitov s makrami. Kontrola modulov len na čítanie je dostupná cez TXLSVBAProject a TXLSVBAModule Zavolajte IXLSWorkbook.HasVBAProject na detekciu obsahu a LoadVBAProjectFromFile / SaveVBAProjectToFile na jeho prenos medzi súbormi

Unicode a medzinárodný text

Všetky reťazce sú natívne Unicode. HotXLS číta a zapisuje súbory Excel vytvorené v akomkoľvek jazyku, vrátane CJK, arabčiny, hebrejčiny, thajčiny a iných písiem, so správnou obojsmernou textovou a podporou poradia čítania
Príklad podpory znakov Unicode

Kontingenčné tabuľky (klasické XLS)

Vytváranie kontingenčných tabuliek zo zdrojového rozsahu pomocou TXLSWorksheet.AddPivotTable, konfigurácia umiestnenia polí a číselných formátov dátových polí, a kontrola modelu kontingenčnej tabuľky cez TXLSWorksheet.PivotTables Pozrite si API kontingenčných tabuliek klasického XLS pre podrobnosti o poliach a filtroch

Výhody

No Office dependency Číta a zapisuje súbory XLS a XLSX priamo na binárnej úrovni. Microsoft Excel ani Office nemusia byť nainštalované, licencované ani spustené. Eliminuje réžiu COM/OLE automatizácie, vyhýba sa obmedzeniam vláknovania uloženým interoperabilitou Office a umožňuje používať HotXLS v serverových a servisných kontextoch, kde inštalácia desktopového Office nie je praktická
High performance Analyzátory BIFF8 a OOXML sú napísané v natívnom Object Pascal bez intermediárnej alokácie XML DOM pre frekventovanú cestu. Veľké zošity so stovkami tisícov riadkov je možné čítať a zapisovať s nízkou špičkovou pamäťou. Deduplikácia zdieľaných reťazcov a kompresia zdieľaných vzorcov sú aplikované automaticky na udržanie malých veľkostí súborov
OLE migration path Povrch API klasickej fasády (zošit, pracovný hárok, rozsah, písmo, ohraničenia, výplň, nastavenie strany) úzko odráža objektový model Excelu známy z OLE Automation. To uľahčuje migráciu existujúcich projektov založených na OLE: nahradte volania COM volaniami HotXLS, odstráňte závislosť na Office a získajte natívny výkon
Dual-facade design Starší kód XLS sa naďalej kompiluje a spúšťa nezmenený oproti lxHandle, pričom nový kód XLSX využíva bohatšiu fasádu lxHandleX. Migrácia jedného formátu súborov naraz je bezpečná a prírastková
Formula engine included Vstavaný viacprechodový výpočtový engine spracováva najbežnejšie funkcie pracovného hárka bez nutnosti opätovného výpočtu v Exceli pri otvorení. Vlastné funkcie sú spracovávané cez spätné volanie OnUserFunction
Easy to use Komponenty Delphi na vloženie (TDataToXLS, TGridToXLS) nevyžadujú pre bežné úlohy exportu žiadny kód. Plynulé API rozsahu podporuje notáciu A1, notáciu R1C1 a indexovanie riadkov/stĺpcov začínajúce od nuly
Thread-safe file I/O Keďže neexistuje žiadny zdieľaný process Office, viacero inštancií TXLSXWorkbook je možné vytvárať a ukladať súbežne v nezávislých vláknach bez synchronizácie, čo robí HotXLS vhodným pre servery na generovanie správ s viacerými vláknami

Kompatibilita

HotXLS je kompatibilný s nasledujúcimi verziami RAD Studio:
Delphi XE5, XE6, XE7, XE8, 10 Seattle, 10.1 Berlin, 10.2 Tokyo, 10.3 Rio, 10.4 Sydney, 11 Alexandria, 12 Athens, 13 Florence
C++Builder XE5, XE6, XE7, XE8, 10 Seattle, 10.1 Berlin, 10.2 Tokyo, 10.3 Rio, 10.4 Sydney, 11 Alexandria, 12 Athens, 13 Florence
Target platforms Windows 32-bitový a 64-bitový
Excel file formats XLS (BIFF8, Excel 97–2003), XLSX (OOXML, Excel 2007+), ODS (OpenDocument 1.2)
Export-only formats HTML, RTF, CSV, TSV

Pozrite tiež