Dokumentace HotXLS

Přehled

HotXLS Logo
HotXLS Excel Read/Write Library je vysokovýkonná komponenta pro čtení a zápis souborů Excel pro Delphi & C++Builder Umožňuje vytvářet nové tabulky Excel a číst nebo upravovat existující sešity XLS a XLSX, aniž by bylo na počítači nutné mít nainstalovaný Microsoft Excel nebo Office
HotXLS je napsán zcela v Object Pascalu. Čte a zapisuje soubory Excel přímo na binární úrovni a na úrovni OOXML, takže nevzniká žádná režie COM/OLE automatizace a neexistuje závislost na přítomnosti nebo licenci Office. HotXLS podporuje Delphi a C++Builder XE5 až 13 Florence
Barevné formátování klasického formátu XLS záměrně zůstává založené na paletě. Viz Barevný model klasického XLS pro popis rozhodnutí ohledně ThemeColor / TintAndShade

Architektura dvojité fasády

HotXLS nabízí dvě souběžně existující fasádní jednotky, takže starší kód pro XLS a nový kód pro XLSX mohou koexistovat bez jakéhokoli refaktorování:
lxHandle Primární fasáda pro formát Excel 97–2003 BIFF8 (.xls), plus export do HTML, RTF, CSV a TSV Veškerý existující uživatelský kód nadále používá tuto jednotku beze změny. Vstupní body: TXLSWorkbook, TXLSWorksheet, IXLSWorkbook, IXLSRange
lxHandleX Primární fasáda pro formát Excel 2007+ OOXML (.xlsx) a OpenDocument Spreadsheet (.ods) — čtení i zápis. Poskytuje vlastní typy sešitů a listů, takže chování specifické pro XLSX není zpětně zaváděno do kódové cesty BIFF. Vstupní body: TXLSXWorkbook, TXLSXWorksheet, TXLSXCell
Obě fasády sdílejí stejný engine pro vyhodnocování vzorců, stejnou vrstvu podpory Unicode a stejný exportní kanál Viz Přehled fasády XLSX pro úplnou hierarchii tříd poskytovaných jednotkou lxHandleX

Rychlý start

Následující ukázky zobrazují minimální kód pro vytvoření sešitu s jedním listem a zápis hodnoty do buňky.

Klasické XLS (lxHandle)

uses lxHandle;

var
  Book: IXLSWorkbook;
  ws:   TXLSWorksheet;
begin
  Book := TXLSWorkbook.Create;
  // Přidat list a pojmenovat jej
  ws := Book.Sheets.Add;
  ws.Name := 'Sheet1';

  // Zapsat hodnoty do buněk pomocí notace A1
  ws.Range['A1'].Value := 'Hello';
  ws.Range['B1'].Value := 42;
  ws.Range['C1'].Formula := '=B1*2';

  // Použít základní formátování
  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');

    // Zapsat textovou a číselnou hodnotu
    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žít formát čísla pro měnu
    cell := ws.Cells[2, 2];
    cell.NumberFormat := '$#,##0.00';

    Book.SaveAs('output.xlsx');
  finally
    Book.Free;
  end;
end;
Podrobnější průvodce pokrývající obě fasády v jednom ukázkovém projektu naleznete v ukázce prohlídky API

Funkce

Vstup/výstup souborů a podpora datových proudů

Čtení existujících souborů Excel, zápis nových nebo existujících souborů Excel, zpracování ochrany heslem klasického XLS a šifrovaného ukládání XLSX, a rychlé získání seznamu názvů listů ze souborů a datových proudů XLS a XLSX bez načítání celého sešitu. Otevření souboru CSV jako sešitu je podporováno prostřednictvím IXLSWorkbook.OpenCSV

Hodnoty buněk a vzorce

Čtení a zápis hodnot buněk všech nativních typů Excel: číslo, řetězec, datum/čas, logická hodnota a vzorec Vestavěný engine pro výpočty vyhodnocuje vzorce v klasických sešitech XLS i XLSX a podporuje:
  • Textové funkce (LEFT, MID, TRIM, SUBSTITUTE, …)
  • Funkce pro datum a pracovní dny (DATE, NETWORKDAYS, WORKDAY, …)
  • Technické funkce a funkce pro převod číselných soustav (BIN2DEC, HEX2DEC, …)
  • Bitové funkce (BITAND, BITOR, BITXOR, …)
  • Statistické a agregační funkce (AVERAGE, SUMIF, COUNTIFS, …)
  • Matematické funkce (ROUND, MOD, POWER, …)
Zpětné volání OnUserFunction umožňuje za běhu zpracovávat vlastní nebo nepodporované funkce listu Viz zpětné volání OnUserFunction pro signaturu a příklady
Příklad vyhodnocení vzorce

Formátování buněk

Plný přístup k atributům vzhledu buněk:
  • Písma — název, velikost, barva (RGB nebo barva motivu + odstín), tučné, kurzíva, podtržení, přeškrtnutí, horní index, dolní index, stín a obrys
  • Zarovnání — vodorovné a svislé zarovnání, orientace textu (úhel), úroveň odsazení, zalamování textu, zmenšení na místo a pořadí čtení (RTL/LTR)
  • Ohraničení — všechny čtyři hrany a úhlopříčky, styl čáry, tloušťka a barva RGB / barva motivu
  • Výplň — plná výplň, vzorové výplně, barvy popředí a pozadí včetně barvy motivu s TintAndShade
  • Formáty čísel — vestavěné a vlastní formátovací řetězce pro datum, čas, měnu, procenta a vědecký zápis
  • Komentáře / anotace — přidání, čtení a stylování komentářů buněk

Operace s oblastmi

IXLSRange (klasická fasáda) a TXLSXRange (fasáda XLSX) poskytují bohatou sadu operací s oblastmi:
  • Sloučení a zrušení sloučení buněk; přístup ke sloučené oblasti libovolné buňky
  • Kopírování, přesouvání, vkládání a mazání oblastí s řízením směru posunu
  • Seskupení a zrušení seskupení řádků nebo sloupců pro zobrazení osnovy/sbalení
  • Automatické přizpůsobení výšky řádku a šířky sloupce obsahu buněk
  • Použití vestavěných pojmenovaných stylů buněk (ApplyBuiltinStyle)
  • Výběry více oblastí (TXLSWorksheet.SelectAreas)
  • Zpětné volání iterace ForEachCell pro dávkové zpracování buněk

Funkce listu

Ovládání na úrovni listu zahrnuje:
  • Název listu, barva záložky, viditelnost (skrytý / velmi skrytý) a navigace podle indexu
  • Ochrana listu s granularitou na úrovni oprávnění; ochrana na úrovni sešitu
  • Ukotvení podoken, rozdělená podokna a pozice posouvání
  • Oblasti automatického filtru s kritérii; pravidla ověřování dat ze seznamu
  • Podmíněné formátování: barevné škály (2 a 3 barvy), datové pruhy a sady ikon
  • Hledání textu a nahrazení textu v rámci listu
  • Možnosti zobrazení: barva mřížky, režim zobrazení vzorců, zobrazení nul, zobrazení záhlaví, zobrazení zprava doleva, zobrazení symbolů osnovy a úroveň přiblížení
  • Strukturované tabulky (TXLSTable / TXLSXTable): přidání, přístup a stylování tabulek Excel s řádky záhlaví a pruhovanými řádky
  • Grafy: přidání listů grafů a vložených grafů prostřednictvím TXLSWorksheetsAddChartSheet a TXLSXChart

Hypertextové odkazy a pojmenované oblasti

Přidání a čtení hypertextových odkazů (URL, mailto a odkazy na buňky v rámci sešitu) prostřednictvím IXLSHyperLinks. Definování a překlad pojmenovaných oblastí na úrovni sešitu a listu prostřednictvím IXLSNames / TXLSXDefinedNames. Pojmenované oblasti lze použít ve vzorcích a přeložit zpět na oblast buněk pomocí RefersToRange

Obrázky a tvary

Vkládání rastrových obrázků (BMP, JPG, PNG, GIF) do listů prostřednictvím TXLSShapes.AddPicture / TXLSXWorksheet.AddImage. Vytváření samostatných textových polí v klasickém XLS prostřednictvím TXLSShapes.AddTextBox. Zachování pravidel konektorů a solveru OfficeArt vytvořených v Excelu v kresbách BIFF8 a zpřístupnění nezpracovaných možností tvarů FOPT prostřednictvím TXLSShape.OfficeArtOptions pro pokročilé pracovní postupy s kresbami

Nastavení stránky a tisk

Plný přístup k rozvržení tisku prostřednictvím IXLSPageSetup:
  • Velikost papíru (A4, Letter, Legal a mnoho dalších; viz PaperSize)
  • Orientace (na výšku / na šířku), okraje, vodorovné / svislé zarovnání na střed
  • Řetězce záhlaví a zápatí s formátovacími kódy Excelu (tučné, kurzíva, číslo stránky, datum atd.; viz Formátovací kódy záhlaví/zápatí)
  • Ruční vodorovné a svislé konce stránek
  • Škálování přizpůsobením na stránky; procento přiblížení; oblast tisku; tituly tisku (opakování řádků / sloupců)
  • Náhledová kvalita; černobíle; tisk mřížky; tisk záhlaví; tisk poznámek

Exportní formáty

Export celých sešitů, jednotlivých listů nebo libovolných oblastí buněk do:
  • HTML — celý dokument nebo fragment vložené tabulky pro náhled nebo e-mailové pracovní postupy; konfigurovatelné prostřednictvím TXLSHTMLExport a TXLSXHtmlExportOptions
  • RTF — formátovaný text pro import do textových procesorů
  • CSV — hodnoty oddělené čárkami s konfigurovatelným oddělovačem a kódováním
  • TSV — hodnoty oddělené tabulátorem
  • ODS — OpenDocument Spreadsheet prostřednictvím fasády lxHandleX

Export databáze a mřížky

Export libovolné datové sady kompatibilní s TDataSet nebo přímo TDBGrid do Excelu, HTML nebo RTF pomocí komponent TDataToXLS nebo TGridToXLS Obě komponenty spouštějí události AfterCell, AfterRow, AfterTitle a AfterGroup pro jemně granulované řízení výstupu a podporují víceúrovňová seskupovací pole

Zachování projektu VBA

HotXLS zachovává obsah projektů VBA při zpracování sešitů s makry. Inspekce modulů jen pro čtení je dostupná prostřednictvím TXLSVBAProject a TXLSVBAModule Voláním IXLSWorkbook.HasVBAProject zjistíte přítomnost obsahu a pomocí LoadVBAProjectFromFile / SaveVBAProjectToFile jej přenesete mezi soubory

Unicode a mezinárodní text

Veškerá práce s řetězci je nativně unicode. HotXLS čte a zapisuje soubory Excel vytvořené v libovolném jazyce, včetně CJK, arabštiny, hebrejštiny, thajštiny a dalších písem, se správnou podporou obousměrného textu a pořadí čtení
Příklad podpory znaků Unicode

Kontingenční tabulky (klasické XLS)

Vytváření kontingenčních tabulek ze zdrojové oblasti pomocí TXLSWorksheet.AddPivotTable, konfigurace umístění polí a formátů čísel datových polí a inspekce modelu kontingenční tabulky prostřednictvím TXLSWorksheet.PivotTables Viz API kontingenčních tabulek klasického XLS pro podrobnosti o polích a filtrech

Výhody

No Office dependency Čte a zapisuje soubory XLS a XLSX přímo na binární úrovni. Microsoft Excel ani Office nemusí být nainstalován, licencován ani spuštěn. To eliminuje režii COM/OLE automatizace, vyhýbá se omezením vláken uložených meziprovozem Office a umožňuje použití HotXLS na straně serveru a v servisních kontextech, kde je instalace desktopového Office nepraktická
High performance Parsery BIFF8 a OOXML jsou napsány v nativním Object Pascalu bez mezilehlé alokace XML DOM pro kritickou cestu. Velké sešity s stovkami tisíc řádků lze číst a zapisovat s nízkou maximální spotřebou paměti. Dedulikace sdílených řetězců a komprese sdílených vzorců jsou automaticky použity pro udržení malých velikostí souborů
OLE migration path Povrch API klasické fasády (sešit, list, oblast, písmo, ohraničení, výplň, nastavení stránky) úzce odráží objektový model Excelu známý z OLE Automation. To usnadňuje migraci existujících projektů založených na OLE: nahraďte volání COM voláními HotXLS, odstraňte závislost na Office a získejte nativní výkon
Dual-facade design Starší kód pro XLS se nadále kompiluje a spouští beze změny s lxHandle, zatímco nový kód pro XLSX používá bohatší fasádu lxHandleX. Migrace po jednom formátu souboru je bezpečná a postupná
Formula engine included Vestavěný víceprůchodový engine pro výpočty zpracovává nejběžnější funkce listů bez nutnosti přepočítání Excelem při otevření. Vlastní funkce jsou zpracovávány prostřednictvím zpětného volání OnUserFunction
Easy to use Zapojitelné komponenty pro Delphi (TDataToXLS, TGridToXLS) nevyžadují žádný kód pro běžné exportní úlohy. Fluentní API oblastí podporuje notaci A1, notaci R1C1 a indexování řádků/sloupců od nuly
Thread-safe file I/O Protože neexistuje žádný sdílený proces Office, lze více instancí TXLSXWorkbook vytvářet a ukládat souběžně na nezávislých vláknech bez synchronizace, čímž je HotXLS vhodný pro vícevláknové servery pro generování sestav

Kompatibilita

HotXLS je kompatibilní s následujícími verzemi 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 32bitový a 64bitový
Excel file formats XLS (BIFF8, Excel 97–2003), XLSX (OOXML, Excel 2007+), ODS (OpenDocument 1.2)
Export-only formats HTML, RTF, CSV, TSV

Viz také