Dokumentacja HotXLS

Obsługa Free Pascal i Lazarus

HotXLS obsługuje Free Pascal 3.2.2 z Lazarus/LCL na Windows Win32 i Win64, w tym API skoroszytów XLS/XLSX, formuły, formatowanie, bezpośrednie strumieniowanie, komponenty eksportu TDataToXLS i TGridToXLS oraz funkcje pomocnicze renderowania

Natywny rdzeń skoroszytów Linux i macOS

Zobacz magazyn plików złożonych, aby poznać API katalogów o ograniczonym zasięgu, jawną natywną własność magazynu, znaczniki czasu i kanoniczne klucze identyfikatorów Classic

Profil opt-in LX_PORTABLE_CORE ujawnia TXLSWorkbooki TXLSXWorkbook bez LCL na Linux i macOS. Natywne Linux x64 i macOS ARM64 zostały skompilowane i wykonane z Free Pascal 3.3.1; guard wersji źródłowej wymaga co najmniej 3.2.2, ale ten minimum nie jest roszczeniem, że każda kombinacja natywnego kompilatora i celu została walidowana

Wstaw cthreadsi cwstring przed jednostkami HotXLS, dodaj Lib do ścieżek jednostek i include oraz zdefiniuj LX_PORTABLE_CORE dla całej budowy. Natywna aplikacja konsolowa nie wymaga Interfaces ani widgetsetu LCL

Wybierz zainstalowaną lokalizację UTF-8 w środowisku aplikacji przy pracy ze ścieżkami systemu plików Unicode; nieprawidłowa albo nie-UTF-8 locale może uczynić natywną konwersję nazw plików RTL stratną; pomocnik walidacji odrzuca takie środowisko jawnie, zamiast zmieniać locale albo zgadywać stronę kodową

program NativeWorkbookExample;
{$mode delphiunicode}
uses
  cthreads, cwstring, SysUtils, lxHandleX;
var
  Workbook: TXLSXWorkbook;
begin
  Workbook:= TXLSXWorkbook.Create;
  try
    Workbook.Sheets.Add('Data').Cells[1, 1].Value:= 5;
    Workbook.Sheets[1].Cells[1, 2].Formula:= 'A1*2';
    if Workbook.Recalculate<> 1 then
      raise Exception.Create('Workbook calculation failed');
    if Workbook.SaveAs('native.xlsx')<> 1 then
      raise Exception.Create('Workbook save failed');
  finally
    Workbook.Free;
  end;
end.
ObszarKontrakt natywnego rdzenia
Pliki skoroszytówTwórz, otwieraj, edytuj, obliczaj i zapisuj Classic BIFF8 XLS, XLSX, obsługiwaną rozszerzoną podzbiór XLSB i obsługiwany podzbiór ODS przez publiczne API skoroszytów, z ich dotychczasowymi kontrolami konwersji i granicami formatów; rekordy Classic BIFF2 z jawnie zadeklarowanymi kodowaniami CP1252 i CP932 zostały też zwalidowane przez import i eksport Unicode BIFF8
Unicode i nazwyTekst skoroszytu zachowuje semantykę UTF-16, a ścieżki systemu plików używają UTF-8 na granicach natywnych; tożsamość nazw zdefiniowanych używa przypiętej kanonicznej normalizacji Unicode 16 i pełnego składania wielkości liter BMP, zachowując symbole, akcenty, tureckie rozróżnienia i tożsamość wielkości liter znaków poza BMP niezależnie od locale hosta; kwalifikowane formuły zachowują swój dokładny zasięg arkusza; zwykłe porządkowanie tekstu arkusza nadal używa porównania locale natywnego RTL
InfrastrukturaNatywne sekcje krytyczne, pełnoszerokościowe identyfikatory wątków, prawdziwe wątki robocze, zarejestrowane wyłączne pliki tymczasowe, atomowa podmiana plików rodzeństwa i losowe bajty systemu operacyjnego są używane bez emulacji Windows
Kompresja i kryptografiaDołączone ZIP/kompresja Pascal i AES pozostają dostępne; klasyczne pliki XLS RC4 i RC4 CryptoAPI mogą być czytane i zapisywane natywnie używając losowych bajtów systemu operacyjnego; natywne odczyty OOXML szyfrowanego używają czystego czytnika plików złożonych; zapis szyfrowanego pliku złożonego OOXML wymaga Windows i rzuca jawną wyjątek platformowy na natywnym Unixie
Funkcje formuł REGEXPrzypięty statyczny backend PCRE2 UTF-16 jest kompilowany na celu natywnym jego kompilatorem C; uruchom sh Lib/thirdparty/build-pcre2-unix.sh przed kompilacją aplikacji zawierających silnik formuł; statyczne cele Linux x64 i macOS ARM64 są dostarczane
Usługi WindowsDostęp do schowka, aktywacja Windows COM, wbudowani dostawcy zapytań ADO/WinHTTP, przechwytywanie geometrii GDI, dekodowanie obrazów tła HTML i starszy eksport PDF rzucają EXLSPlatformUnsupported na swoich jawnych granicach; własni dostawcy zapytań i dostawcy tekstu pozostają użyteczni
Starsze komponentyModel skoroszytu Classic oraz czytnik/zapisywacz BIFF są dostępne w rdzeniu natywnym; pakiet runtime LCL, komponenty eksportu zbiorów/siatki i kontrolki wizualne pozostają komponentami Windows/LCL; klasyczne metody schowka, eksport HTML i starszy eksport PDF rzucają jawną wyjątek platformowy na natywnym Unixie
Tekstowe formuły zorientowane bajtowoFunkcje wymagające aktywnej strony ANSI/DBCS Windows zwracają na natywnym Unixie jawny wynik nieobsługiwanej formuły (#NAME?); nie jest wybierany żaden domniemany substytut locale albo strony kodowej

Metody otwierania i zapisu zachowują swoje zwykłe kontrakty kodów wyników i diagnostyk; bezpośrednie wywołania granic platformowych mogą rzucać EXLSPlatformUnsupported; obsłuż ten wyjątek przy wywoływaniu usługi wyłącznie-Windows z współdzielonego kodu aplikacji

Odtwarzalna walidacja natywna

Uruchom pomocnik walidacji na natywnym gościu z istniejącym toolchainem Free Pascal, Python 3 i natywnym kompilatorem C; wybierz nowy albo pusty katalog wyjścia poza checkoutem źródeł, na systemie plików gościa

python3 Tests/Lazarus/run_native_core.py --fpc /path/to/fpc --output /guest-local/hotxls-validation
python3 Tests/Lazarus/run_native_core.py --fpc /path/to/fpc --config /path/to/fpc.cfg --output /guest-local/hotxls-validation-2

Pomocnik kopiuje i haszuje wejścia źródłowe, normalizuje nazwy plików jednostek Pascal w prywatnej kopii budowy dla wrażliwej na wielkość liter wyszukiwania nazw plików FPC, buduje PCRE2 lokalnie i uruchomia świadków rdzenia, AES, kompresji, REGEX, publicznych skoroszytów i integracji; zachowuje manifesty źródeł, logi kompilatora, artefakty i porażki, bez zmieniania checkoutu, bez instalowania narzędzi i bez edycji konfiguracji kompilatora; buildki macOS ARM64 jawnie celują w macOS 11 lub nowszy

Świadkowie integracji obejmują ścieżki Unicode, fixtury XLSB autorowane w Excelu, pamięci podręczne formuł i przeliczanie, powtarzane otwarcia, rzadkie notatki ODS i ochronę, odrzucenie sprawdzanej konwersji, anulowanie zachowujące cele wywołującego, niezmienną wyszukiwarkę nazw z zasięgiem, realne ujęcie porażek wątków roboczych i kryptograficzne bajty losowe

Kontrakty Classic XLS natywne

Użyj lxHandle dla Classic TXLSWorkbooki lxHandleX dla TXLSXWorkbook; klasyczny Recalculate zwraca liczbę błędów, tak więc zero znaczy sukces; jego metoda Calculate zwraca wynik formuły; przypisania Formula komórki klasycznej wymagają wiodącego =; metody otwierania i zapisu skoroszytu zachowują swoje ustalone wyjście sukcesu równe 1

Natywna implementacja magazynu Classic używa prawdziwej hierarchii plików złożonych i tożsamości strumieni, zachowując zagnieżdżone zasięgi, dane MiniFAT i rozszerzone łańcuchy DIFAT; ładunki strumieni są materializowane, a zapisujący odrzuca wyjście agregatowe poza jego obsługiwanymi granicami bufora/sektora ze znakiem 32-bitowym przed emisją; to nie jest implementacja magazynu strumieniowego wielogigabajtowego

Natywny magazyn złożony dostarcza bezpośrednie operacje strumieni, wyliczanie, metadane i operacje kopiowania; rollback transakcji, blokowanie regionów, przenoszenie i nieobsługiwane tryby wykluczenia zwracają jawne błędy magazynu; nie emuluje usług Windows COM, schowka ani GDI

Natywne zapisy plików klasycznych serializują przed atomową podmianą zarejestrowanego pliku rodzeństwa; zapisy strumieniowe wywołującego etapują kompletny plik złożony przed kopiowaniem na oryginalnej pozycji, zachowując prefiksy i porażki anulowania przed commitom; finalne powiadomienie o postępie pozostaje nieanulowalne; bezpośrednie zapisy pomocników magazynu złożonego podążają za swoim zwykłym kontraktem bezpośredniego zapisu, a nie za transakcją zapisu publicznego skoroszytu

Zwykłe właściwości podsumowań i podsumowań dokumentu używają ograniczonych standardowych zbiorów właściwości OLE z tekstem Unicode i znacznikami czasu UTC FILETIME; te strumienie właściwości pozostają plaintextem, gdy dane skoroszytu klasycznego są szyfrowane, a nagłówek RC4 CryptoAPI jawnie zapisuje ten wybór; nazwy zdefiniowane współdzielą przypięte kanoniczne klucze identyfikatorów używane przez fasadę XLSX, zachowując przy tym swój oryginalny zapis i jawny zasięg arkusza; zakodowane dane rysunków PNG/JPEG pozostają dostępne dla modelu; natywna konwersja bitmapa/metafile wymaga oddzielnego obsługiwanego renderera, a w przeciwnym razie rzuca EXLSPlatformUnsupported

Skompiluj Tests/Lazarus/HotXLSNativeClassicWorkbookSmoke.lpr z tymi samymi opcjami rdzenia natywnego, a potem przekaż Tests/Fixtures/classic-native/native-classic.xls, dyspozycyjną ścieżkę wyjścia gościa lokalnego i Tests/Fixtures/classic-native/native-classic-encrypted.xls; kontrolki pokrywają pamięci podręczne autorowane w Excelu, przeliczanie, dokładne nazwy Unicode, round-tripy zwykłe i szyfrowane, niezależnie dekodowane znaczniki czasu właściwości, powtarzane otwarcia, ponad 16 MB danych SST i zachowanie wyjścia wywołującego

Starsze kodowanie bajtów BIFF

TXLSWorkbook.SetCodePage wybiera jawne kodowanie bajtów używane przez SaveAs(..., xlExcel5), z CP1252 jako domyślnym; import pliku BIFF2–BIFF5 z użytecznym niezerowym rekordem CODEPAGE także wybiera tę stronę dla późniejszych starszych zapisów

Starsze etykiety komórek, stałe tekstowe formuł i tablice, zapamiętane ciągi formuł, nazwy zdefiniowane, nazwy arkuszy i odwołania, nazwy czcionek, formaty liczbowe, nazwy stylów, nagłówki, stopki oraz zwykły tekst komentarzy używają tej zadeklarowanej strony, a nie locale systemu operacyjnego albo UTF-8

Długości rekordów i offsety strumieni arkuszy liczą zakodowane bajty; istniejące limity 255-bajtowe starszych etykiet i literałów formuł skracają wyłącznie na granicy całego znaku, więc znak dwubajtowy CP932 nigdy nie zostaje rozcięty; nazwy i metadane z długością jedno-bajtową odrzucają zakodowany tekst dłuższy niż ich przedstawialna długość, zamiast emitować nieprawidłową długość

Tekst, który nie daje się przejechać round-tripem przez wybraną stronę kodową, rzuca EConvertError, zanim mógłby po cichu stać się znakiem zastępczym albo najlepszego dopasowania; wybierz stronę reprezentującą tekst dokumentu albo zapisz jako BIFF8 dla ciągów Unicode

Ciągi pamięci podręcznej formuł rozpięte na rekordy CONTINUE są składane jako bajty przed dekodowaniem, więc granica rekordu może rozciąć znak dwubajtowy bez psucia zapamiętanej wartości

Zmiana wybranej strony przebudowuje typowane starsze bajty formuł i nazw zdefiniowanych z ich modelu Unicode; zapisy BIFF8 nadal używają Unicode, a ich wartość CODEPAGE na dysku pozostaje 1200

Zaimportowane rekordy wykresów BIFF5 zachowują swoją oryginalną stronę kodową dla inspekcji typowanych serii i podpiętych tytułów, włącznie z po edycji strony kodowej skoroszytu albo kopii wykresu; zapis na inną stronę jawnie przekodowuje obsługiwane SeriesText, zwykłe zapamiętane etykiety i ciągi formuł, nagłówki, stopki oraz nazwy zewnętrznych arkuszy bieżącego skoroszytu, a nie reinterpretuje zachowanych bajtów pod nową deklaracją

Kontynuowany tekst wykresów, niemodelowane starsze kodowania zewnętrznych arkuszy i nieprzejrzyste starsze rekordy bajtów tekstu odrzucają migrację strony kodowej z EConvertError; nieprzestawialny obsługiwany tekst także jest odrzucany, a publiczny zapis skoroszytu zachowuje cel wywołującego przed commitom; ten kontrakt tekstu nie obiecuje pełnej konwersji natywnego wyglądu wykresów

Własne nazwy stylów BIFF5 zaczynają się bezpośrednio po jedno-bajtowej zakodowanej długości, a BIFF5 SeriesText ma identyfikator i jedno-bajtową zakodowaną długość bez flagi Unicode; BIFF8 SeriesText dodaje swoją flagę Unicode, a konwersja obsługiwanego tekstu wykresów aktualizuje ten rekord i wersję BOF wykresu razem

Niepuste nagłówki i stopki wykresów BIFF5 używają jedno-bajtowej zakodowanej długości z maksimum 255 bajtów; zapamiętane rekordy LABEL i STRING używają długości dwubajtowych, podczas gdy nagłówki i stopki BIFF8 używają dwubajtowej długości UTF-16 plus swojej flagi Unicode; migracja sprawdza rzeczywisty układ każdego rekordu i odrzuca zbyt duży starszy nagłówek albo stopkę z ERangeError przed jej dopisaniem

HotXLS interpretuje starsze bajty według ich zadeklarowanej strony na Windows, Linux i macOS; zainstalowana buildka Excel 16.0 build 20430 niezależnie zademonstrowała ograniczenie odbiorcy: interpretowała starsze bajty według lokalnego Windows CP936 nawet po zmianie samego rekordu CODEPAGE pliku natywnego na CP1252 albo CP932, więc poprawne zadeklarowane bajty nie gwarantują zgodnego tekstu w tej konfiguracji odbiorcy

Zachowaj rzeczywistą deklarację kodowania dokumentu i testuj aplikację odbierającą przy rozprowadzaniu BIFF5 między różne konfiguracje locale; Unicode BIFF8 omija tę szczególną granicę współpracy starszych bajtów

Ta korekta kodowania bajtów zachowuje istniejący limit rozmiaru rekordu zwykłych komentarzy BIFF5; nie dodaje do starszego rekordu pól autora komentarza, formatowania rich-text ani geometrii kształtu

Edycja źródła modułów VBA używa zadeklarowanej strony kodowej bajtów projektu i zachowuje prefiks binarny przed offsetem źródła, włącznie z osadzonymi bajtami null; to zmienia zapisany tekst źródłowy i nie wykonuje makr

Skompresowany Unicode BIFF8 z fHighByte = 0 mapuje każdy bajt bezpośrednio na jednostkę kodową UTF-16 od U+0000 do U+00FF; to nie jest CP1252, UTF-8 ani starsza strona kodowa pliku, nawet gdy niestandardowy rekord CODEPAGE pojawia się w innym względzie BIFF8 pliku

Natywne formuły tekstowe zachowują długości i pozycje UTF-16, włącznie z jednostkami kodowymi par surrogate; Unicode LOWER, UPPER, SEARCH, delimitery TEXTBEFORE/TEXTAFTER bez rozróżniania wielkości liter, nagłówki pól bazodanowych, kryteria bez rozróżniania wielkości liter i dynamiczne klucze tekstowe używają świadomych Unicode danych znakowych natywnego kompilatora, a nie wyłącznie-ASCII funkcji składania wielkości liter locale C hosta, podczas gdy zwykłe porządkowanie arkusza zachowuje swoje istniejące porównanie locale

Natywne dopasowywanie nazw lokalnych LET/LAMBDA i klasyfikacja magazynu tablic lokalnych używają tego samego składania wielkości liter świadomego Unicode, więc odpowiedniki wielkości liter rozwiązują poprawne przechwycone wiązanie i zachowują jego kształt tablicy; to nie zmienia przypiętego publicznego kontraktu tożsamości nazw zdefiniowanych

Klasyczne FindText i ReplaceText bez rozróżniania wielkości liter zachowują dopasowanie znaków Unicode dla wyszukiwań literalnych i dzikich kart Excela na natywnym FPC; MatchCase nadal rozróżnia wielkość liter, zamiana literalna zachowuje zachowanie zamiany wszystkich, zamiana dzikich kart zachowuje swoje istniejące zachowanie skrajnie-lewej rozpiętości, a komórki formuł pozostają wykluczone

Skompiluj Tests/Lazarus/HotXLSNativeLegacyEncodingSmoke.lpr z opcjami rdzenia natywnego i przekaż dyspozycyjny katalog wyjścia, a następnie Tests/Fixtures/legacy-encoding/native-biff5-cp936-chart.xls; świadek sprawdza niezależnie zadeklarowane bajty CP1252, CP932 i CP936, każdy offset arkusza, zmiany strony kodowej, granice kontynuacji dwubajtowych, import skompresowanego BIFF8, obliczanie formuł, natywnie autorowany tekst wykresów i zachowanie celu przy nieudanym zapisie

Pełny instalator

Pełny instalator wykrywa Lazarusa i obsługuje instalację bez RAD Studio. Wybierz Lazarus / Free Pascal na stronie integracji z IDE, aby zainstalować pakiet środowiska uruchomieniowego, jednostki zgodności i skrypty budowania; opcja ta jest domyślnie zaznaczona, gdy Lazarus jest jedynym wykrytym IDE

Na stronie kompilacji po instalacji wybierz pakiet środowiska uruchomieniowego Free Pascal dla Win32 albo Win64. Cel jest dostępny, gdy wykryto jego kompilator, RTL oraz jednostki LCL i LazUtils; gdy cel jest niedostępny, nadal możesz zainstalować źródła pakietu i skompilować je później

Pakiet jest wyłącznie środowiska uruchomieniowego i dodaje się go jako zależność projektu w Lazarusie. Instalator nie kompiluje dem VCL przy użyciu Free Pascala

Budowanie i testy

Otwórz Lib/FPC/HotXLSLaz.lpk w Lazarusie i skompiluj pakiet środowiska uruchomieniowego albo uruchom te polecenia z katalogu HotXLS

build-FPC-Lib.cmd Win64
Tests\Lazarus\Run-HotXLSLazarusSmoke.cmd Win64
build-FPC-Lib.cmd Win32
Tests\Lazarus\Run-HotXLSLazarusSmoke.cmd Win32

Ustaw LAZARUS_DIR, aby wybrać instalację; FPC_EXE i LAZBUILD_EXE pozwalają w razie potrzeby wskazać jawne pliki wykonywalne kompilatora i narzędzia budowania pakietów

Wybrana instalacja musi zawierać FPC oraz skompilowane jednostki LCL/LazUtils dla architektury docelowej; wyjścia i konfiguracja narzędzia budowania pakietów są przechowywane w osobnych katalogach architektur

Konfiguracja aplikacji

Dodaj Lib i Lib/FPC do ścieżki wyszukiwania jednostek oraz Lib do ścieżki wyszukiwania include, albo dodaj pakiet środowiska uruchomieniowego jako zależność projektu Lazarusa

Umieść Interfaces przed jednostkami HotXLS na liście uses aplikacji, w tym w aplikacjach konsolowych; inicjuje to zestaw widżetów LCL i konwersję UTF-8 na granicach RTL/LCL

program WorkbookExample;
{$mode delphiunicode}
uses
  Interfaces, SysUtils, lxHandleX;
var
  Workbook: TXLSXWorkbook;
begin
  Workbook:= TXLSXWorkbook.Create;
  try
    Workbook.AddSheet('Data');
    Workbook.Sheets[1].Cells[1, 1].Value:= 'Hello';
    if Workbook.SaveAs('example.xlsx')<> 1 then
      raise Exception.Create('Workbook save failed');
  finally
    Workbook.Free;
  end;
end.

Jednostki źródłowe HotXLS wewnętrznie wybierają semantykę Unicode Delphi, więc ciągi, znaki i tekst formuł zachowują zachowanie UTF-16; kod aplikacji może używać preferowanego trybu Pascala

Szczegóły zgodności