HotXLS-dokumentation

Free Pascal- och Lazarus-stöd

HotXLS stöder Free Pascal 3.2.2 med Lazarus/LCL på Windows Win32 och Win64, inklusive arbetsboks-API:erna för XLS/XLSX, formler, formatering, direkt strömning, exportkomponenterna TDataToXLS och TGridToXLS samt renderingshjälpmedel

Inbyggd Linux- och macOS-arbetsbokskärna

Se compound file-lagring för omfångsberoende katalog-API:er, explicit inbyggt lagringsägande, tidsstämplar och kanoniska Classic-identifierarnycklar

Den frivilliga profilen LX_PORTABLE_CORE exponerar TXLSWorkbook och TXLSXWorkbook utan LCL på Linux och macOS. Inbyggd Linux x64 och macOS ARM64 har kompilerats och körts med Free Pascal 3.3.1; källversionskontrollen kräver minst 3.2.2, men det minimivärdet är inte ett påstående att varje inbyggd kompilator- och målkombination har validerats

Lägg cthreads och cwstring före HotXLS-enheterna, lägg till Lib i enhets- och inkluderingssökvägarna, och definiera LX_PORTABLE_CORE för hela bygget. Ett inbyggt konsolprogram kräver inte Interfaces eller en LCL-widgetset

Välj en installerad UTF-8-locale i programmiljön när du arbetar med Unicode-filsökvägar. En ogiltig eller icke-UTF-8-locale kan göra den inbyggda RTL-filnamnskonverteringen förlustig; valideringshjälparen avvisar den miljön explicit i stället för att ändra locale eller gissa en kodsid

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.
OmrådeKontrakt för inbyggd kärna
ArbetsboksfilerSkapa, öppna, redigera, beräkna och spara Classic BIFF8 XLS, XLSX, den stödda utökade XLSB-delmängden och den stödda ODS-delmängden via de publika arbetsboks-API:erna, med sina befintliga konverteringskontroller och formatgränser. Classic BIFF2-poster med explicit deklarerade CP1252- och CP932-kodningar har också validerats genom import och Unicode BIFF8-export
Unicode och namnArbetsbokstext behåller UTF-16-semantik och filsökvägar använder UTF-8 vid de inbyggda gränssnitten. Identitet för definierade namn använder fastnålad Unicode 16-kanonisk normalisering och full BMP-skiftlägesvikning, med bevarande av symboler, diakritiska tecken, turkiska skillnader och skiftlägesidentitet för astraltecken oberoende av värdlocolen; kvalificerade formler behåller sitt exakta bladomfång. Ordinarie kalkylbladstextordning använder fortfarande den inbyggda RTL-locales jämförelse
InfrastrukturInbyggda kritiska sektioner, fullbredds trådidentifierare, riktiga arbetstrådar, registrerade exklusiva temporära filer, atomär ersättning av syskonfil och operativsystemets slumpbyte används utan Windows-emulering
Komprimering och kryptografiDen medföljande Pascal-ZIP/komprimeringen och AES förblir tillgängliga. Classic RC4- och RC4 CryptoAPI XLS-filer kan läsas och skrivas inbyggt med operativsystemets slumpbyte. Inbyggda krypterade OOXML-läsningar använder den rena compound-file-läsaren; att skriva en krypterad OOXML compound-fil kräver Windows och utlöser ett explicit plattformsundantag på inbyggd Unix
REGEX-funktioner i formlerDen fastnålade statiska PCRE2 UTF-16-backend kompileras på det inbyggda målet med dess C-kompilator. Kör sh Lib/thirdparty/build-pcre2-unix.sh innan program som innehåller formelmotorn kompileras; statiska mål för Linux x64 och macOS ARM64 tillhandahålls
WindowstjänsterUrklippsåtkomst, Windows COM-aktivering, inbyggda ADO/WinHTTP-frågeproviders, GDI-geometrifångst, HTML-bakgrundsbildsavkodning och äldre PDF-export utlöser EXLSPlatformUnsupported vid sina explicita gränssnitt. Anpassade frågeproviders och textproviders förblir användbara
Äldre komponenterDen klassiska arbetsboksmodellen och BIFF-läsaren/skrivaren är tillgängliga i den inbyggda kärnan. LCL-runtime-paketet, dataset-/rutnäetsexportkomponenterna och visuella kontroller förblir Windows/LCL-komponenter. Klassiska urklippsmetoder, HTML-export och äldre PDF-export utlöser explicita plattformsundantag på inbyggd Unix
Byteorienterade textformlerFunktioner som kräver Windowss aktiva ANSI/DBCS-kodsid returnerar ett explicit ostött formelresultat (#NAME?) på inbyggd Unix; ingen implicit locale- eller kodsidersättning väljs

Öppnings- och sparmetoder behåller sina normala resultatkod- och diagnostikkontrakt. Direkta plattformsgräns-anrop kan utlösa EXLSPlatformUnsupported; hantera det undantaget när en endast-Windows-tjänst anropas från delad programkod

Reproducerbar inbyggd validering

Kör valideringshjälparen på den inbyggda gästen med en befintlig Free Pascal-verktygskedja, Python 3 och en inbyggd C-kompilator. Välj en ny eller tom utdatakatalog utanför källutcheckningen på gästfilsystemet

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

Hjälparen kopierar och hashar källindata, normaliserar Pascal-enhetsfilnamn i den privata byggkopian för FPC:s skiftlägeskänsliga filnamnssökning, bygger PCRE2 lokalt och kör vittnen för kärna, AES, komprimering, REGEX, publika arbetsböcker och integration. Den bevarar källmanifest, kompilatorloggar, artefakter och fel utan att ändra utcheckningen, installera verktyg eller redigera kompilatorkonfigurationen. macOS ARM64-byggen riktar sig explicit till macOS 11 eller senare

Integrationsvittnena omfattar Unicode-sökvägar, Excel-skapade XLSB-förhandsfiler, formelcache:er och omberäkning, upprepade öppningar, glesa ODS-anteckningar och skydd, avvisning av kontrollerad konvertering, avbrott som bevarar anroparens destinationer, invariant uppslagning av omfångsberoende namn, inneslutning av riktiga arbetarfel och kryptografiska slumpbyte

Inbyggda Classic XLS-kontrakt

Använd lxHandle för Classic TXLSWorkbook och lxHandleX för TXLSXWorkbook. Classic Recalculate returnerar antalet fel, så noll betyder framgång; dess metod Calculate returnerar ett formelresultat. Classic celltilldelningar av Formula kräver ett inledande =. Arbetsbokens öppnings- och sparmetoder behåller sitt etablerade framgångsresultat 1

Den inbyggda Classic-lagringsimplementationen använder riktig compound-file-hierarki och strömidentiteter, med bevarande av nästlade omfång, MiniFAT-data och utökade DIFAT-kedjor. Strömnyttolaster materialiseras och skrivaren avvisar aggregerad utmatning utöver sina stödda signerade 32-bitars buffert-/sektorgränser innan den emitteras; detta är inte en streaminglagringsimplementation för flera gigabyte

Inbyggd compound-lagring tillhandahåller direkta strömoperationer, uppräkning, metadata och kopieringsoperationer. Transaktionsrollback, regionlåsning, flytt och ostödda uteslutningslägen returnerar explicita lagraingsfel. Den emulerar inte Windows COM, urklipp eller GDI-tjänster

Inbyggd Classic-filsparning serialiserar innan en registrerad syskonfil ersätts atomärt. Anroparens strömsparningar mellanlagrar hela compound-filen innan kopiering sker på ursprunglig position, med bevarande av prefix och avbrottsfel innan genomförande. Det sista förloppsmeddelandet förblir icke-avbrytbart. Direkta compound-lagringshjälpar skrivningar följer sitt ordinära direkt-skrivningskontrakt i stället för den publika arbetsbokssparningstransaktionen

Ordinarie egenskaper för sammanfattning och dokumentsammanfattning använder avgränsade standard-OLE-egenskapsuppsättningar med Unicode-text och UTC FILETIME-tidsstämplar. Dessa egenskapsströmmar förblir i klartext när Classic-arbetsboksdata krypteras, och RC4 CryptoAPI-huvudet registrerar uttryckligen det valet. Definierade namn delar de fastnålade kanoniska identifierarnycklarna som XLSX-fasaden använder, medan de behåller sin ursprungliga stavning och sitt explicita kalkylbladsomfång. Kodade PNG/JPEG-ritningsdata förblir tillgängliga för modellen; inbyggd bitmapp/metafilkonvertering kräver en separat stödd renderare och utlöser annars EXLSPlatformUnsupported

Kompilera Tests/Lazarus/HotXLSNativeClassicWorkbookSmoke.lpr med samma inbyggda kärnalternativ, och skicka sedan Tests/Fixtures/classic-native/native-classic.xls, en engångs gästlokal utdatasökväg och Tests/Fixtures/classic-native/native-classic-encrypted.xls. Kontrollerna täcker Excel-skapade cache:er, omberäkning, exakta Unicode-namn, rena och krypterade round trips, oberoende avkodade egenskapstidsstämplar, upprepade öppningar, mer än 16 MB SST-data och bevarande av anroparens utdata

Äldre BIFF-bytekodning

TXLSWorkbook.SetCodePage väljer den explicita bytekodningen som SaveAs(..., xlExcel5) använder, med CP1252 som standard; import av en BIFF2–BIFF5-fil med en användbar CODEPAGE-post skild från noll väljer också den sidan för senare äldre sparningar

Äldre celletiketter, formeltextkonstanter och matriser, cachade formulärsträngar, definierade namn, kalkylbladsnamn och referenser, typsnittsnamn, talformat, stilnamn, sidhuvuden, sidfötter och ordinär kommentartext använder den deklarerade sidan i stället för operativsystemets locale eller UTF-8

Postlängder och kalkylbladsströmoffset räknar kodade byte; de befintliga 255-byte-gränserna för äldre etiketter och formlitteraler trunkerar bara vid en hel teckengräns, så ett CP932-dubbelbyte-tecken delas aldrig; namn och metadata med en byte lång längd avvisar kodad text längre än deras representerbara längd i stället för att emittera en ogiltig längd

Text som inte kan round-trippa genom den valda kodsidan utlöser EConvertError innan den tyst kan bli ett ersättningstecken eller bäst-anpassning-tecken; välj en sid som representerar dokumenttexten, eller spara som BIFF8 för Unicode-strängar

Formelcache-strängar som spänner över CONTINUE-poster monteras som byte före avkodning, så en postgräns kan dela ett dubbelbyte-tecken utan att förstöra det cachade värdet

Att ändra den valda sidan bygger upp typade äldre formel- och definierat-namn-byte från sin Unicode-modell igen; BIFF8-sparningar fortsätter använda Unicode och deras CODEPAGE-värde på disk förblir 1200

Importerade BIFF5-diagnosposter behåller sin ursprungliga kodsid för typad serieinspektion och bifogad titelinspektion, även efter en redigering av arbetsbokens kodsid eller en diagramkopia; sparande till en annan sid transkoder explicit SeriesText som stöds, vanliga cachade etiketter och formelsträngar, sidhuvuden, sidfötter och namn på externa blad i aktuell arbetsbok, i stället för att tolka bevarade byte på nytt under den nya deklarationen

Fortsatt diagramtext, omodellerade äldre externa bladkodningar och opaka äldre byte-textposter avvisar en kodsidmigrering med EConvertError; stödd text som inte kan representeras avvisas också, och den publika arbetsbokssparningen bevarar anroparens destination innan genomförande; detta textkontrakt lovar inte fullständig konvertering av inbyggt diagramutseende

Anpassade stilnamn i BIFF5 börjar omedelbart efter den en byte långa kodade längden, medan BIFF5 SeriesText har en identifierare och en en byte lång kodad längd utan Unicode-flagga; BIFF8 SeriesText lägger till sin Unicode-flagga, och konvertering av stödd diagramtext uppdaterar den posten och diagramets BOF-version tillsammans

Icke-tomma BIFF5-diagramhuvuden och sidfötter använder en en byte lång kodad längd med max 255 byte; cachade LABEL- och STRING-poster använder två byte långa längder, medan BIFF8-huvuden och sidfötter använder en två byte lång UTF-16-längd plus sin Unicode-flagga; migreringen kontrollerar varje posts verkliga layout och avvisar ett överdimensionerat äldre sidhuvud eller sidfot med ERangeError innan det läggs till

HotXLS tolkar äldre byte med deras deklarerade sid på Windows, Linux och macOS; den installerade Excel 16.0 build 20430 demonstrerade oberoende en mottagarbegränsning: den tolkade äldre byte med sin lokala Windows CP936 även efter att en inbyggd fils CODEPAGE-post ensam ändrats till CP1252 eller CP932, så korrekta deklarerade byte garanterar inte matchande text i den mottagarkonfigurationen

Bevara dokumentets faktiska kodningsdeklaration och testa det mottagande programmet när BIFF5 distribueras över olika locale-konfigurationer; Unicode BIFF8 undviker denna särskilda gräns för samverkan med äldre byte

Denna korrigering av bytekodningen behåller den befintliga poststorleksgränsen för BIFF5-ordinära kommentarer; den lägger inte till fält för kommentarsförfattare, formatering av rik text eller shape-geometri till den äldre posten

Redigering av VBA-modulkällkod använder projektets deklarerade bytekodsid och bevarar det binära prefixet före käll-offset, inklusive inbäddade nullbyte; detta ändrar lagrad källtext och kör inte makron

BIFF8-komprimerad Unicode med fHighByte = 0 mappar varje byte direkt till en UTF-16-kodenhet U+0000 till U+00FF; det är inte CP1252, UTF-8 eller filens äldre kodsid, även när en ickestandard CODEPAGE-post förekommer i en i övrigt BIFF8-fil

Inbyggda textformler behåller UTF-16-längder och positioner, inklusive surrogatpar-kodenheter; Unicode LOWER, UPPER, SEARCH, skiftlägesokänsliga avgränsare i TEXTBEFORE/TEXTAFTER, databasfältrubriker, skiftlägesokänsliga kriterier och dynamiska textnycklar använder den inbyggda kompilatorns Unicode-teckendata i stället för värd-C-locolens ASCII-bara skiftlägesfunktioner, medan ordinär kalkylbladsordning behåller sin befintliga locale-jämförelse

Inbyggd matchning av lokala namn i LET/LAMBDA och klassificering av lokal matrislagring använder samma Unicode-medvetna skiftlägeshantering, så skiftlägesmotsvarigheter löser upp rätt fångad bindning och behåller dess matrisform; detta ändrar inte kontraktet för den fastnålade publika identiteten för definierade namn

Klassisk skiftlägesokänslig FindText och ReplaceText behåller Unicode-teckenmatchning för literala sökningar och Excel-jokerteckensökningar på inbyggd FPC; MatchCase skiljer fortfarande skiftläge, literal ersättning behåller sitt ersätt-alla-beteende, jokerteckensersättning behåller sitt befintliga vänster-spann-beteende, och formelceller förblir uteslutna

Kompilera Tests/Lazarus/HotXLSNativeLegacyEncodingSmoke.lpr med alternativen för den inbyggda kärnan och skicka en engångs utdatakatalog följt av Tests/Fixtures/legacy-encoding/native-biff5-cp936-chart.xls; vittnet kontrollerar deklarerade CP1252-, CP932- och CP936-byte oberoende, varje kalkylbladsoffset, ändringar av kodsid, gränser för dubbelbyte-fortsättning, importerad komprimerad BIFF8, formelberäkning, inbyggt skapad diagramtext och bevarande av destinationen vid misslyckad sparning

Fullständigt installationsprogram

Det fullständiga installationsprogrammet detekterar Lazarus och stöder installation utan RAD Studio. Välj Lazarus / Free Pascal på sidan IDE Integration för att installera runtime-paketet, kompatibilitetsenheterna och byggskripten; alternativet är förvalt när Lazarus är den enda detekterade IDE:n

På sidan Post-install Compilation väljer du Free Pascal runtime-paketet för Win32 eller Win64. Ett mål är tillgängligt när dess kompilator samt RTL-, LCL- och LazUtils-enheter har hittats; du kan fortfarande installera paketkällorna när ett mål saknas och kompilera dem senare

Paketet är endast för runtime och läggs till som ett projektberoende i Lazarus. Installationsprogrammet kompilerar inte VCL-demonerna med Free Pascal

Bygge och test

Öppna Lib/FPC/HotXLSLaz.lpk i Lazarus och kompilera runtime-paketet, eller kör dessa kommandon från HotXLS-katalogen

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

Sätt LAZARUS_DIR för att välja en installation; FPC_EXE och LAZBUILD_EXE kan vid behov välja explicita kompilator- och paketbyggarprogram

Den valda installationen måste innehålla FPC och kompilerade LCL/LazUtils-enheter för målarkitekturen; utdata och paketbyggarkonfiguration hålls i separata arkitekturkataloger

Programkonfiguration

Lägg till Lib och Lib/FPC till enhetssökvägen och Lib till inkluderingssökvägen, eller lägg till runtime-paketet som ett Lazarus-projektberoende

Placera Interfaces före HotXLS-enheterna i programmets uses-lista, inklusive konsolprogram; detta initierar LCL-widgetsetet och UTF-8-konverteringen vid RTL/LCL-gränssnitten

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.

HotXLS-källenheterna väljer Delphi Unicode-semantik internt så att strängar, tecken och formeltext behåller UTF-16-beteendet; programkoden får använda sitt föredragna Pascal-läge

Kompatibilitetsdetaljer