Dokumentacja HotXLS

Klasa TXLSXWorkbook

Kontener najwyższego poziomu dla skoroszytu Excel 2007+ (.xlsx). Zadeklarowany w lxHandleX. Przechowuje kolekcję TXLSXSheets i udostępnia punkty wejścia SaveAs / Open dla skoroszytów OOXML, importu CSV / TSV i przepływów pracy odczytu/zapisu OpenDocument Spreadsheet (.ods)

Deklaracja


type

  TXLSXFileFormat = (xlsxOpenXMLWorkbook, xlsxOpenDocumentSpreadsheet);



  TODSExportOptions = class

    constructor Create;

    property Generator: WideString;

    property IncludeCharts: Boolean;

    property IncludeImages: Boolean;

  end;



  TXLSXWorkbook = class

    constructor Create;

    destructor Destroy; override;

    function SaveAs(const FileName: WideString): Integer; overload;

    function SaveAs(const FileName: WideString; FileFormat: TXLSXFileFormat): Integer; overload;

    function SaveAs(Stream: TStream): Integer; overload;

    function SaveAs(Stream: TStream; FileFormat: TXLSXFileFormat): Integer; overload;

    function Open(const FileName: WideString): Integer; overload;

    function Open(const FileName: WideString; const Password: WideString): Integer; overload;

    function Open(Stream: TStream): Integer; overload;

    function OpenCSV(const FileName: WideString): Integer; overload;

    function OpenCSV(const FileName: WideString; ASeparator: WideChar;

      ADetectTypes: Boolean): Integer; overload;

    function OpenCSV(Stream: TStream): Integer; overload;

    function OpenCSV(Stream: TStream; ASeparator: WideChar;

      ADetectTypes: Boolean): Integer; overload;

    function OpenODS(const FileName: WideString): Integer; overload;

    function OpenODS(Stream: TStream): Integer; overload;

    function SaveAsODS(const FileName: WideString): Integer; overload;

    function SaveAsODS(Stream: TStream): Integer; overload;

    function SaveAsODS(const FileName: WideString; Options: TODSExportOptions): Integer; overload;

    function SaveAsODS(Stream: TStream; Options: TODSExportOptions): Integer; overload;

    function GetODSSheetNames(const FileName: WideString; AList: TStrings): Integer; overload;

    function GetODSSheetNames(Stream: TStream; AList: TStrings): Integer; overload;

    function GetSheetNames(const FileName: WideString; AList: TStrings): Integer; overload;

    function GetSheetNames(Stream: TStream; AList: TStrings): Integer; overload;

    function SaveAsCSV(const FileName: WideString): Integer; overload;

    function SaveAsCSV(const FileName: WideString; SheetIndex: Integer; Delimiter: WideChar): Integer; overload;

    function SaveAsCSV(Stream: TStream): Integer; overload;

    function SaveAsCSV(Stream: TStream; SheetIndex: Integer; Delimiter: WideChar): Integer; overload;

    function SaveAsHTML(const FileName: WideString): Integer; overload;

    function SaveAsHTML(const FileName: WideString; Options: TXLSXHtmlExportOptions): Integer; overload;

    function SaveAsHTML(const FileName: WideString; SheetIndex: Integer): Integer; overload;

    function SaveAsHTML(const FileName: WideString; SheetIndex: Integer; Options: TXLSXHtmlExportOptions): Integer; overload;

    function SaveAsHTML(Stream: TStream): Integer; overload;

    function SaveAsHTML(Stream: TStream; Options: TXLSXHtmlExportOptions): Integer; overload;

    function SaveAsHTML(Stream: TStream; SheetIndex: Integer): Integer; overload;

    function SaveAsHTML(Stream: TStream; SheetIndex: Integer; Options: TXLSXHtmlExportOptions): Integer; overload;

    function SaveAsRTF(const FileName: WideString): Integer; overload;

    function SaveAsRTF(const FileName: WideString; SheetIndex: Integer): Integer; overload;

    function SaveAsRTF(Stream: TStream): Integer; overload;

    function SaveAsRTF(Stream: TStream; SheetIndex: Integer): Integer; overload;

    // AES encryption (ECMA-376 Standard Encryption) write path.

    // OpenEncrypted still raises for encrypted packages.

    function SaveAsEncrypted(const FileName, APassword: WideString): Integer;

    function OpenEncrypted(const FileName, APassword: WideString): Integer;

    function CanReadEncrypted(const FileName: WideString): Boolean;

    function Calculate(const Formula: WideString): Variant;

    property OnUserFunction: TXLSUserFunctionEvent;

    property OnUserFunctionEx: TXLSUserFunctionExEvent;

    // Document properties (docProps/core.xml + docProps/app.xml).

    property Title, Author, Subject, Keywords, Description,

             Category, LastModifiedBy, Company,

             Application, AppVersion: WideString;

    property Created, Modified: TDateTime;

    // Workbook protection (16-bit legacy hash).

    procedure ProtectWorkbook; overload;

    procedure ProtectWorkbook(const APassword: WideString); overload;

    procedure ProtectWorkbook(const APassword: WideString; ALockStructure, ALockWindows: Boolean); overload;

    procedure UnProtectWorkbook;

    property IsWorkbookProtected: Boolean;

    property LockStructure, LockWindows: Boolean;

    // VBA project payload (round-trips byte-for-byte). Workbook is saved

    // with macro-enabled content type when HasVbaProject is True.

    procedure LoadVbaProjectFromFile(const AFileName: WideString);

    procedure ClearVbaProject;

    function HasVbaProject: Boolean;

    property VbaProjectDefined: Boolean;

    property VbaProject: AnsiString;

    property ParsedVBAProject: TXLSVBAProject;

    // Chart sheet helper — creates a sheet flagged IsChartSheet and

    // seeds Charts[0] with a default full-page anchor.

    function AddChartSheet(const AName: WideString;

      AChartType: TXLSXChartType; const ATitle: WideString): TXLSXWorksheet;

    // Streaming SaveAs path (TXLSWideStringBuilder + one sheet at a time).

    property StreamingWrite: Boolean;

    // Workbook-level collections.

    property ActiveSheet: Integer;

    property Minimized: Boolean;

    property WindowHidden: Boolean;

    property ShowHorizontalScroll: Boolean;

    property ShowVerticalScroll: Boolean;

    property ShowSheetTabs: Boolean;

    property XWindow: Integer;

    property YWindow: Integer;

    property WindowWidth: Integer;

    property WindowHeight: Integer;

    property TabRatio: Integer;

    property FirstSheet: Integer;

    property AutoFilterDateGrouping: Boolean;

    property Date1904: Boolean;

    property SourceFormat: TXLSXFileFormat;

    property IndexedColor[Index: Integer]: LongWord;

    function  HasCustomIndexedColor(Index: Integer): Boolean;

    function  CustomIndexedColorCount: Integer;

    procedure ResetIndexedColors;

    property Sheets: TXLSXSheets;

    property Fonts: TXLSXFonts;

    property Fills: TXLSXFills;

    property Borders: TXLSXBorders;

    property NumberFormats: TXLSXNumberFormats;

    property Alignments: TXLSXAlignments;

    property DefinedNames: TXLSXDefinedNames;

    property ExternalLinks: TXLSXExternalLinks;

  end;

      

Elementy

Sheets arkusz kolekcja. See TXLSXSheets
Fonts skoroszyt-level czcionka palette. komórki pick czcionka przez setting TXLSXCell.FontIndex do 1-oparty indeks do ten kolekcja. See TXLSXFont / TXLSXFonts
Fills Paleta wypełnień na poziomie skoroszytu. Komórki wybierają wypełnienie przez ustawienie TXLSXCell.FillIndex na 1-bazowy indeks w tej kolekcji. Zobacz TXLSXFill / TXLSXFills
Borders skoroszyt-level obramowanie palette. komórki pick obramowanie przez setting TXLSXCell.BorderIndex do 1-oparty indeks do ten kolekcja. See TXLSXBorder / TXLSXBorders
NumberFormats Paleta niestandardowych formatów liczb na poziomie skoroszytu. Komórki wybierają format przez ustawienie TXLSXCell.NumberFormatIndex na 1-bazowy indeks w tej kolekcji. Zobacz TXLSXNumberFormat / TXLSXNumberFormats
DefinedNames skoroszyt-level named zakresy (skoroszyt-scoped lub arkusz-scoped). See TXLSXDefinedName / TXLSXDefinedNames
Calculate Kompiluje i oblicza ciąg formuły Excela względem aktywnego arkusza, a wiodące = jest akceptowane. Odwołania do komórek, zakresy, formuły zapisane w odwołanych komórkach, odwołania międzyarkuszowe, zakresy nazwanych definicji oraz obsługiwane funkcje tekstowe, daty, workday, engineering/base-conversion, bitwise, statystyczne, agregujące i matematyczne są obliczane przez wspólny silnik formuł HotXLS. Zobacz OnUserFunction dla funkcji niestandardowych lub nieobsługiwanych
OnUserFunction, OnUserFunctionEx Callback używany przez Calculate gdy formuła calls custom lub unsupported funkcja. See OnUserFunction / OnUserFunctionEx callback
GetSheetNames(FileName, AList), GetSheetNames(Stream, AList) Odczytuje xl/workbook.xml i dopisuje nazwy arkuszy do AList w kolejności skoroszytu bez ładowania XML arkuszy. Wersja dla strumienia oczekuje kompletnego strumienia pakietu XLSX. Zwraca liczbę odczytanych nazw albo -1, gdy nie można otworzyć pakietu
Alignments skoroszyt-level komórka-alignment palette. komórki pick wpis przez setting TXLSXCell.AlignmentIndex do 1-oparty indeks do ten kolekcja. See TXLSXAlignment
Document properties Tytuł, Autor, Temat, Słowa kluczowe, Opis, Kategoria, LastModifiedBy, Company, Application, AppVersion, Created, Modified. Ustawienie któregokolwiek z nich w SaveAs wypełnia docProps/core.xml i docProps/app.xml (w przeciwnym razie skoroszyt zachowuje minimalny zestaw części)
ProtectWorkbook / UnProtectWorkbook skoroszyt protection toggle z optional 16-bit legacy hasło hash i LockStructure / LockWindows flags. Reflected as <workbookProtection> w xl/skoroszyt.xml
LoadVbaProjectFromFile / VbaProject / HasVbaProject / VbaProjectDefined Importuje surowy ładunek vbaProject.bin; VbaProject udostępnia bajty; HasVbaProject i tylko do odczytu VbaProjectDefined informują, czy ładunek jest obecny. Zapisz z rozszerzeniem .xlsm, gdy makra mają być włączone w Excelu
ParsedVBAProject Tylko do odczytu, sparsowany widok bieżącego ładunku vbaProject.bin. Gdy ładunek jest prawidłowym magazynem OLE VBA, zwraca TXLSVBAProject udostępniający nazwy modułów i tekst źródłowy; w przeciwnym razie zwraca nil. Surowy ładunek VbaProject pozostaje nadrzędnym źródłem bajtów dla round-trip SaveAs/Open
AddChartSheet(Name, Type, Title) Tworzy arkusz oznaczony jako IsChartSheet = True i wypełnia Charts[0] sensownym domyślnym zakotwiczeniem na całą stronę. SaveAs zapisuje takie arkusze do xl/chartsheets/sheetN.xml. Zobacz TXLSXChart
StreamingWrite Gdy True, SaveAs używa WriteWorksheetXmlStreaming dla każdego arkusza - nie jest utrzymywana pamięć podręczna sheetXmls, a sharedStrings.xml jest emitowany jako ostatni po wypełnieniu SST przez każdy arkusz. W połączeniu z TXLSWideStringBuilder na wiersz utrzymuje to liniowe zużycie pamięci na dużych arkuszach. Domyślnie False (dotychczasowe zachowanie)
SaveAsEncrypted / OpenEncrypted / CanReadEncrypted Obsługa zapisu zgodna z ECMA-376 Standard Encryption. SaveAsEncrypted zapisuje zgodny ze standardem kontener OLE Compound File chroniony AES-128 dla niepustych haseł, z przyspieszeniem AES-NI, gdy jest dostępne, i przenośnym fallbackiem programowym w przeciwnym razie. Zaszyfrowany wynik otwiera się w Excelu 2007 i nowszym przy użyciu hasła użytego do zapisu. CanReadEncrypted wykrywa bajty magiczne OLE2; OpenEncrypted transparentnie spada do zwykłego Open dla niezaszyfrowanych plików i nadal zgłasza EXlsxEncryptionNotImplemented dla zaszyfrowanych pakietów, dopóki nie pojawi się obsługa odszyfrowania
SaveAs(FileName) Zapisuje skoroszyt do podanego pliku. Zwraca 1 przy powodzeniu, wartość ujemną przy niepowodzeniu. Jeśli skoroszyt nie ma arkuszy, przed zapisem dodawany jest domyślny Sheet1
SaveAs(FileName, FileFormat) Akceptuje xlsxOpenXMLWorkbook dla wyjścia OOXML albo xlsxOpenDocumentSpreadsheet dla bezpośredniego pakietu OpenDocument Spreadsheet (.ods). SaveAsODS jest nazwanym skrótem dla ścieżki ODS i daje ten sam format wyjściowy z opcjonalną kontrolą TODSExportOptions
SaveAs(Stream) / SaveAs(Stream, FileFormat) Zapisuje skoroszyt bezpośrednio do dowolnego TStream. Przeładowanie FileFormat akceptuje xlsxOpenXMLWorkbook albo xlsxOpenDocumentSpreadsheet, więc nadaje się do generowania XLSX lub ODS w pamięci oraz do ścieżek przechowywania BLOB. Zwraca 1 przy powodzeniu
Open(FileName) Odczytuje archiwum OOXML .xlsx i zastępuje kolekcję Sheets jego zawartością. Zwraca 1 przy powodzeniu
Open(FileName, Password) Reserved dla future encrypted XLSX obsługa. Behaves like Open(FileName) today — hasło jest ignored
Open(Stream) Importuje tekst CSV lub TSV do skoroszytu z automatycznym wykrywaniem separatora (,, ;, tab albo pipe), wykrywaniem kodowania UTF-8 / UTF-16 na podstawie BOM, polami w cudzysłowie zgodnymi z RFC 4180 oraz opcjonalnym wyznaczaniem typu wartości przez przeciążenia ADetectTypes. Wywołanie Open(FileName) dla .csv albo .tsv automatycznie kieruje do tego importera. Zobacz OpenCSV method
OpenCSV(FileName) / OpenCSV(Stream) Importuje pakiet OpenDocument Spreadsheet (.ods) z pliku lub strumienia. Czytnik ładuje content.xml, współdzielone style z styles.xml i ustawienia widoku, gdy są obecne, zachowując nazwy arkuszy, wartości skalarne, buforowane wyniki formuł, podstawową konwersję odwołań w formułach, powtórzone wiersze/kolumny/komórki, scalone zakresy, rich text, hiperłącza, komentarze, osadzone obrazy, osadzone wykresy, ukryte wiersze/kolumny/arkusze, wysokości wierszy, szerokości kolumn, dziedziczone/domyslne style, formaty liczb/daty/czasu/waluty/naukowe/łamkowe, stan ochrony komórek i arkuszy, nazwane zakresy, obszary wydruku, ręczne podziały stron, zamrożone okienka, zakresy AutoFiltra, grupy outline wierszy/kolumn, nagłówki i stopki, sprawdzanie poprawności danych z podpowiedziami, formatowanie warunkowe z formułami/skalami kolorów/słupkami danych oraz kolor karty arkusza. Pełna semantyka OpenFormula, klucze ochrony ODS, geometria komentarzy, zaawansowane formatowanie komentarzy i funkcje pakietu spoza zawartości arkusza nie są konwertowane
OpenODS(FileName) / OpenODS(Stream) Zapisuje skoroszyt jako prawidłowy pakiet OpenDocument Spreadsheet. Zapisuje bezpośrednio ODF mimetype, manifest, metadane, style i zawartość arkusza, przenosząc typowane wartości, formuły, style, rich text, wymiary, scalania, hiperłącza, obrazy, wykresy, nazwane zakresy, zakresy AutoFiltra, formatowanie warunkowe, sprawdzanie poprawności danych, zamrożone okienka, ustawienia strony, nagłówki i stopki, obszary wydruku, ręczne podziały stron, grupy outline, kolor karty i widoczność arkusza tam, gdzie te funkcje są reprezentowane w modelu skoroszytu HotXLS
SaveAsODS(FileName) / SaveAsODS(Stream) Steruje eksportem ODS. Generator zastępuje wartość meta:generator w meta.xml; pusta wartość używa wbudowanego ciągu generatora HotXLS. IncludeCharts i IncludeImages mają domyślnie True i, gdy są False, usuwają odpowiednie ramki rysunków, części pakietu i wpisy manifestu razem, aby wynik nie zawierał osieroconych odwołań do wykresów lub obrazów. Instancja opcji należy do wywołującego i musi zostać zwolniona
TODSExportOptions Odczytuje tylko nazwy arkuszy ODS z content.xml do AList bez resetowania ani wypełniania skoroszytu. Użyj tego, gdy okno wyboru pliku albo przepływ importu potrzebuje nazw arkuszy przed załadowaniem skoroszytu
GetODSSheetNames(FileName, AList), GetODSSheetNames(Stream, AList) Cztery przeciążenia (FileName lub Stream × domyślny aktywny arkusz / jawny SheetIndex + Delimiter). Zapisuje wybrany arkusz jako UTF-8 CSV z BOM. Wartości dat są zapisywane jako yyyy-mm-dd hh:nn:ss; komórki formuł są obliczane przed eksportem, a tekst formuły jest używany tylko wtedy, gdy obliczenie nie jest dostępne. Zwraca 0 przy powodzeniu
SaveAsCSV overloads Przeciążenia opcji akceptują TXLSXHtmlExportOptions dla Title, WriteDocument, IncludeStyles, IncludeBOM i TableClass. Ustaw WriteDocument na False dla fragmentu tabeli; ustaw IncludeBOM na False, gdy osadzasz wynik w istniejącej odpowiedzi UTF-8. Wyeksportowany wynik zachowuje hiperłącza komórek jako kotwice <a> i zakotwiczone obrazy jako wbudowane URI obrazów data:; eksport na poziomie skoroszytu zawiera kotwice poza wypełnionymi komórkami. Komentarze komórek są też emitowane jako escapowane atrybuty <td> title, a eksport na poziomie skoroszytu zawiera kotwice tylko z komentarzami. Gdy IncludeStyles jest włączone, jawne wartości ColWidth są emitowane jako szerokości <col>, a jawne wartości RowHeight jako style wysokości <tr>. Fragmenty rich text są emitowane jako escapowane elementy <span> z wbudowanymi stylami fontu, koloru, pogrubienia i podkreślenia, gdy IncludeStyles jest włączone. Obramowania komórek są emitowane jako reguły CSS border-left, border-right, border-top i border-bottom, gdy IncludeStyles jest włączone. Ukryte wiersze i kolumny oznaczone RowHidden / ColHidden, plus jawne kolumny o zerowej szerokości, są pomijane w wygenerowanej tabeli i <colgroup>. Ustawienia wyrównania pionowego są emitowane jako reguły CSS vertical-align, gdy IncludeStyles jest włączone
SaveAsHTML overloads Cztery przeciążenia (FileName lub Stream × domyślny aktywny arkusz / jawny SheetIndex). Zapisuje wybrany arkusz jako dokument RTF 1.6 z prostą tabelą. Szerokości kolumn są wyliczane z danych ColWidth (1 jednostka znaku ≈ 96 twips; domyślnie 809 twips). Stosowane są pogrubienie / kursywa / rozmiar czcionki per komórka; znaki nie-ASCII są kodowane jako podpisane 16-bitowe escape'y RTF Unicode \\uN?. Scalonych komórek nie rozciąga się. Zwraca 0 przy powodzeniu
SaveAsRTF overloads 1-bazowy indeks aktywnego (wybranego) arkusza (0, gdy żaden nie jest aktywny), zgodny z klasycznym silnikiem XLS ActiveSheetIndex. SaveAs zapisuje activeTab="N" na <workbookView> (sam atrybut OOXML activeTab pozostaje 0-bazowy), gdy trzeba emitować opcje widoku skoroszytu, i oznacza odpowiadający arkusz tabSelected="1"
ActiveSheet Flagi wyglądu okna skoroszytu zapisywane w <workbookView>. Minimized zapisuje minimized="1", WindowHidden zapisuje visibility="hidden", a ShowHorizontalScroll / ShowVerticalScroll ukrywają lub pokazują paski przewijania skoroszytu. Open zachowuje wszystkie cztery wartości
Minimized / WindowHidden / ShowHorizontalScroll / ShowVerticalScroll Geometria okna skoroszytu zapisywana w <workbookView>. XWindow i YWindow przechowują położenie okna, a WindowWidth i WindowHeight jego rozmiar. Wartości są ograniczane do 0..65535 i wracają bez zmian przy odczycie
XWindow / YWindow / WindowWidth / WindowHeight Opcje widoku okna skoroszytu zapisywane w <workbookView>. ShowSheetTabs ukrywa lub pokazuje pasek kart arkuszy, TabRatio kontroluje podział szerokości między paskiem kart a paskiem przewijania i jest ograniczany do 0..1000, FirstSheet wybiera pierwszy widoczny tab jako 0-bazowy indeks arkusza i ogranicza się do istniejącego arkusza, a AutoFilterDateGrouping steruje grupowaniem dat Excela w rozwijanych listach AutoFiltra. Open zachowuje wszystkie cztery wartości
ShowSheetTabs / TabRatio / FirstSheet / AutoFilterDateGrouping Baza daty skoroszytu. False (domyślnie) = epoka Windows 1900; True = epoka Mac 1904 (przesuwa każdy serial daty o 1462 dni). Ustaw to przed przypisaniem wartości komórek TDateTime, aby Excel wyświetlił tę samą datę kalendarzową
Date1904 Wartość ARGB dla danego slotu palety kolorów OOXML (0..63). Odczyt zwraca nadpisanie użytkownika, jeśli jest ustawione, w przeciwnym razie wbudowany domyślny OOXML (XlsxDefaultIndexedPalette). Zapis nadpisuje slot N; SaveAs wypisuje wtedy pełny blok <indexedColors> ze wszystkimi 64 slotami
SourceFormat Reports package family loaded przez most recent successful Open lub OpenODS call. It zwraca xlsxOpenXMLWorkbook dla XLSX i xlsxOpenDocumentSpreadsheet dla ODS; newly created skoroszyt reports xlsxOpenXMLWorkbook until plik jest opened
IndexedColor[Index] HasCustomIndexedColor(N) zwraca True, gdy slot N został jawnie nadpisany. CustomIndexedColorCount zwraca liczbę nadpisanych slotów (0 = brak bloku <colors> emitowanego przez SaveAs). ResetIndexedColors usuwa każde nadpisanie i przywraca domyślną paletę
HasCustomIndexedColor / CustomIndexedColorCount / ResetIndexedColors Kolekcja zewnętrznych odwołań do skoroszytów. Każdy wpis TXLSXExternalLink przechowuje docelowy URL i listę SheetNames. SaveAs emituje blok <externalReferences> w xl/workbook.xml oraz odpowiednie części xl/externalLinks/. Open zachowuje Target i SheetNames; buforowane wartości komórek wewnątrz <sheetDataSet> nie są zachowywane
ExternalLinks Kolekcja zewnętrznych odwołań skoroszytu. Każdy wpis TXLSXExternalLink przechowuje docelowy URL oraz listę SheetNames. SaveAs emituje blok <externalReferences> w xl/workbook.xml oraz odpowiadające mu części xl/externalLinks/. Open zachowuje wartości Target i SheetNames przy round-tripie; buforowane wartości komórek wewnątrz <sheetDataSet> nie są zachowywane

Przykład

Zapis i ponowne otwieranie skoroszytu:

uses lxHandleX;



var

  wb: TXLSXWorkbook;

begin

  wb := TXLSXWorkbook.Create;

  try

    wb.Sheets.Add('Demo').Cells.Item[1, 1].Value := 'Hello';

    wb.SaveAs('demo.xlsx');



    wb.Open('demo.xlsx');

    ShowMessage(wb.Sheets[0].Cells.Item[1, 1].Value);

  finally

    wb.Free;

  end;

end;

    

Zobacz też