Suporte a Free Pascal e Lazarus

O HotXLS suporta Free Pascal 3.2.2 com Lazarus/LCL em Windows Win32 e Win64, incluindo as APIs de pasta de trabalho XLS/XLSX, fórmulas, formatação, streaming direto, os componentes de exportação TDataToXLS e TGridToXLS e os auxiliares de renderização

Núcleo de pasta de trabalho nativo para Linux e macOS

Veja armazenamento de arquivo composto para APIs de diretórios com escopo, propriedade nativa explícita de armazenamento, timestamps e chaves canônicas de identificadores Classic

O perfil opcional LX_PORTABLE_CORE expõe TXLSWorkbook e TXLSXWorkbook sem LCL no Linux e no macOS. Linux x64 nativo e macOS ARM64 foram compilados e executados com Free Pascal 3.3.1; a guarda de versão do código-fonte exige pelo menos 3.2.2, mas esse mínimo não é uma afirmação de que toda combinação de compilador nativo e alvo foi validada

Coloque cthreads e cwstring antes das unidades do HotXLS, adicione Lib aos caminhos de pesquisa de unidades e de includes, e defina LX_PORTABLE_CORE para toda a compilação. Um aplicativo de console nativo não exige Interfaces nem um widgetset da LCL

Selecione uma localidade UTF-8 instalada no ambiente do aplicativo ao trabalhar com caminhos de sistema de arquivos Unicode. Uma localidade inválida ou não UTF-8 pode tornar a conversão de nomes de arquivo da RTL nativa com perdas; o helper de validação rejeita explicitamente esse ambiente em vez de mudar a localidade ou adivinhar uma página de código

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.

Os métodos de abrir e salvar retêm seus contratos normais de código de resultado e de diagnósticos. Chamadas diretas em limites de plataforma podem gerar EXLSPlatformUnsupported; trate essa exceção ao invocar um serviço exclusivo do Windows a partir de código de aplicativo compartilhado

Validação nativa reproduzível

Execute o helper de validação no convidado nativo com um toolchain Free Pascal existente, Python 3 e um compilador C nativo. Escolha um diretório de saída novo ou vazio fora do checkout do código-fonte, no sistema de arquivos do convidado

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

O helper copia e calcula o hash das entradas de origem, normaliza nomes de arquivo de unidades Pascal na cópia privada de build para a busca de nomes de arquivo sensível a maiúsculas do FPC, compila o PCRE2 localmente, e executa testemunhas de núcleo, AES, compressão, REGEX, pasta de trabalho pública e integração. Ele preserva manifestos de origem, logs do compilador, artefatos e falhas sem alterar o checkout, instalar ferramentas ou editar a configuração do compilador. As compilações macOS ARM64 visam explicitamente macOS 11 ou posterior

As testemunhas de integração incluem caminhos Unicode, fixtures XLSB criados pelo Excel, caches de fórmulas e recálculo, aberturas repetidas, notas ODS esparsas e proteção, rejeição de conversão verificada, cancelamento que preserva destinos do chamador, busca invariante de nomes com escopo, contenção de falhas reais de workers e bytes aleatórios criptográficos

Contratos Classic XLS nativos

Use lxHandle para o TXLSWorkbook Classic e lxHandleX para o TXLSXWorkbook. O Recalculate Classic retorna uma contagem de erros, de modo que zero significa sucesso; o método Calculate dele retorna um resultado de fórmula. Atribuições de Formula em células Classic exigem um = inicial. Os métodos de abrir e salvar da pasta de trabalho mantêm seu resultado de sucesso estabelecido de 1

A implementação nativa de armazenamento Classic usa hierarquia e identidades de stream reais de arquivo composto, preservando escopos aninhados, dados de MiniFAT e cadeias estendidas de DIFAT. Payloads de stream são materializados, e o gravador rejeita saída agregada além de seus limites suportados de buffer/setor signed de 32 bits antes de emiti-la; esta não é uma implementação de armazenamento em streaming de múltiplos gigabytes

O armazenamento composto nativo fornece operações diretas de stream, enumeração, metadados e cópia. Rollback de transação, travamento de região, movimento e modos de exclusão sem suporte retornam erros explícitos de armazenamento. Ele não emula serviços COM, de área de transferência nem GDI do Windows

Salvamentos nativos de arquivos Classic serializam antes de substituir atomicamente um arquivo irmão registrado. Salvamentos em stream do chamador preparam o arquivo composto completo antes de copiar na posição original, preservando prefixos e falhas de cancelamento antes do commit. A notificação final de progresso permanece não cancelável. Gravações de helpers diretos de armazenamento composto seguem seu contrato ordinário de gravação direta, e não a transação pública de salvamento da pasta de trabalho

Propriedades comuns e de resumo de documento usam conjuntos de propriedades OLE padrão limitados, com texto Unicode e timestamps UTC FILETIME. Esses streams de propriedades permanecem em texto puro quando os dados da pasta de trabalho Classic estão criptografados, e o cabeçalho RC4 CryptoAPI registra explicitamente essa escolha. Nomes definidos compartilham as chaves canônicas de identificadores fixadas usadas pela facade XLSX, retendo a grafia original e o escopo explícito de planilha. Dados de desenhos PNG/JPEG codificados permanecem disponíveis ao modelo; a conversão nativa de bitmap/metafile exige um renderizador separado com suporte e, caso contrário, gera EXLSPlatformUnsupported

Compile Tests/Lazarus/HotXLSNativeClassicWorkbookSmoke.lpr com as mesmas opções do núcleo nativo e, em seguida, passe Tests/Fixtures/classic-native/native-classic.xls, um caminho de saída descartável local do convidado e Tests/Fixtures/classic-native/native-classic-encrypted.xls. Os controles cobrem caches criados pelo Excel, recálculo, nomes Unicode exatos, round trips simples e criptografados, timestamps de propriedades decodificados de forma independente, aberturas repetidas, mais de 16 MB de dados de SST e preservação da saída do chamador

Codificação de bytes BIFF legada

TXLSWorkbook.SetCodePage seleciona a codificação de bytes explícita usada por SaveAs(..., xlExcel5), com CP1252 como padrão; importar um arquivo BIFF2–BIFF5 com um record CODEPAGE utilizável diferente de zero também seleciona essa página para salvamentos legados posteriores

Rótulos de células legados, constantes de texto de fórmulas e arrays, strings de fórmulas em cache, nomes definidos, nomes e referências de planilhas, nomes de fontes, formatos numéricos, nomes de estilos, cabeçalhos, rodapés e texto de comentários comuns usam essa página declarada, e não a localidade do sistema operacional nem UTF-8

Comprimentos de registros e offsets de stream de planilha contam bytes codificados; os limites existentes de 255 bytes para rótulos legados e literais de fórmula truncam apenas em um limite de caractere inteiro, de modo que um caractere de dois bytes CP932 nunca é dividido; nomes e metadados com comprimento de um byte rejeitam texto codificado mais longo do que seu comprimento representável, em vez de emitir um comprimento inválido

Texto que não faz round-trip pela página de código selecionada gera EConvertError antes que possa se tornar silenciosamente um caractere de substituição ou de melhor encaixe; selecione uma página que represente o texto do documento, ou salve como BIFF8 para strings Unicode

Strings de cache de fórmulas que atravessam records CONTINUE são montadas como bytes antes da decodificação, de modo que um limite de registro pode dividir um caractere de dois bytes sem corromper o valor em cache

Mudar a página selecionada reconstrói os bytes legados tipados de fórmulas e de nomes definidos a partir do modelo Unicode delas; salvamentos BIFF8 continuam usando Unicode, e o valor CODEPAGE em disco delas permanece 1200

Records de gráfico BIFF5 importados retêm sua página de código original para inspeção tipada de séries e de títulos anexados, inclusive após uma edição da página de código da pasta de trabalho ou uma cópia de gráfico; salvar em uma página diferente transcodifica explicitamente SeriesText, rótulos simples em cache e strings de fórmulas, cabeçalhos, rodapés e nomes de planilhas externas da pasta de trabalho atual com suporte, em vez de reinterpretar bytes preservados sob a nova declaração

Texto de gráfico continuado, codificações legadas de planilhas externas sem modelo e registros legados de texto em bytes opacos rejeitam uma migração de página de código com EConvertError; texto suportado não representável também é rejeitado, e o salvamento público da pasta de trabalho preserva o destino do chamador antes do commit; este contrato de texto não promete conversão completa da aparência nativa de gráficos

Nomes de estilos personalizados BIFF5 começam imediatamente após o comprimento codificado de um byte, enquanto o SeriesText BIFF5 tem um identificador e um comprimento codificado de um byte sem flag Unicode; o SeriesText BIFF8 acrescenta sua flag Unicode, e converter texto de gráfico suportado atualiza esse record e a versão de BOF do gráfico juntos

Cabeçalhos e rodapés de gráfico BIFF5 não vazios usam um comprimento codificado de um byte com máximo de 255 bytes; records em cache LABEL e STRING usam comprimentos de dois bytes, enquanto cabeçalhos e rodapés BIFF8 usam um comprimento UTF-16 de dois bytes mais a flag Unicode deles; a migração verifica o layout real de cada record e rejeita um cabeçalho ou rodapé legado grande demais com ERangeError antes de anexá-lo

O HotXLS interpreta bytes legados usando a página declarada deles no Windows, no Linux e no macOS; a compilação instalada do Excel 16.0 build 20430 demonstrou de forma independente uma limitação do destinatário: ela interpretou bytes legados usando o CP936 local do Windows mesmo depois de o record CODEPAGE de um arquivo nativo ter sido alterado sozinho para CP1252 ou CP932, de modo que bytes declarados corretos não garantem texto correspondente nessa configuração de destinatário

Preserve a declaração real de codificação do documento e teste o aplicativo receptor ao distribuir BIFF5 entre configurações de localidade diferentes; o BIFF8 Unicode evita esse limite específico de interoperabilidade de bytes legados

Esta correção de codificação de bytes retém o limite existente de tamanho de record de comentários comuns BIFF5; ela não acrescenta campos de autor de comentário, formatação rich-text ou geometria de forma ao record legado

A edição de código-fonte de módulos VBA usa a página de código de bytes declarada do projeto e preserva o prefixo binário antes do offset do código-fonte, incluindo bytes nulos embutidos; isso altera o texto de origem armazenado e não executa macros

Unicode comprimido BIFF8 com fHighByte = 0 mapeia cada byte diretamente para uma unidade de código UTF-16 de U+0000 a U+00FF; não é CP1252, UTF-8 nem a página de código legada do arquivo, mesmo quando um record CODEPAGE não padrão aparece em um arquivo BIFF8

Fórmulas de texto nativas retêm comprimentos e posições UTF-16, incluindo unidades de código de pares surrogate; delimitadores insensíveis a maiúsculas Unicode de LOWER, UPPER, SEARCH, TEXTBEFORE/TEXTAFTER, cabeçalhos de campos de banco de dados, critérios insensíveis a maiúsculas e chaves de texto dinâmicas usam os dados de caracteres Unicode do compilador nativo em vez das funções ASCII-only de caixa da localidade C do host, enquanto a ordenação comum de planilha retém sua comparação de localidade existente

A correspondência de nomes locais de LET/LAMBDA nativa e a classificação de armazenamento de arrays locais usam a mesma caixa ciente de Unicode, de modo que pares de caixa resolvem o vínculo capturado correto e retêm a forma de array dele; isso não muda o contrato público fixado de identidade de nomes definidos

FindText e ReplaceText Classic insensíveis a maiúsculas retêm correspondência de caracteres Unicode para buscas literais e com wildcards do Excel no FPC nativo; MatchCase ainda distingue caixa, a substituição literal mantém o comportamento de substituir tudo, a substituição com wildcard mantém o comportamento existente de intervalo mais à esquerda, e células de fórmula continuam excluídas

Compile Tests/Lazarus/HotXLSNativeLegacyEncodingSmoke.lpr com as opções do núcleo nativo e passe um diretório de saída descartável seguido de Tests/Fixtures/legacy-encoding/native-biff5-cp936-chart.xls; a testemunha verifica bytes declarados CP1252, CP932 e CP936 de forma independente, cada offset de planilha, mudanças de página de código, fronteiras de continuação de dois bytes, importação BIFF8 comprimida, cálculo de fórmulas, texto de gráfico criado nativamente e preservação do destino em salvamento com falha

Instalador completo

O instalador completo detecta o Lazarus e suporta a instalação sem RAD Studio. Selecione Lazarus / Free Pascal na página de integração com IDE para instalar o pacote de runtime, as units de compatibilidade e os scripts de build; essa opção vem selecionada por padrão quando o Lazarus é a única IDE detectada

Na página de compilação pós-instalação, selecione o pacote de runtime Free Pascal para Win32 ou Win64. Um alvo fica disponível quando o compilador, a RTL, a LCL e as units LazUtils dele são detectados; você ainda pode instalar as fontes do pacote quando um alvo não está disponível e compilá-las depois

O pacote é somente de runtime e é adicionado como dependência de projeto no Lazarus. O instalador não compila as demos VCL com Free Pascal

Compilação e testes

Abra o Lib/FPC/HotXLSLaz.lpk no Lazarus e compile o pacote de runtime, ou execute estes comandos a partir do diretório do HotXLS

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

Defina LAZARUS_DIR para selecionar uma instalação; FPC_EXE e LAZBUILD_EXE podem selecionar executáveis explícitos de compilador e de construção de pacotes quando necessário

A instalação selecionada deve conter o FPC e unidades LCL/LazUtils compiladas para a arquitetura de destino; as saídas e a configuração do construtor de pacotes ficam em diretórios separados por arquitetura

Configuração do aplicativo

Adicione Lib e Lib/FPC ao caminho de pesquisa de unidades e Lib ao caminho de pesquisa de includes, ou adicione o pacote de runtime como dependência do projeto Lazarus

Coloque Interfaces antes das unidades do HotXLS na lista de uses do aplicativo, incluindo aplicativos de console; isso inicializa o widgetset da LCL e a conversão UTF-8 nas fronteiras 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.

As unidades de origem do HotXLS selecionam internamente a semântica Unicode do Delphi, de modo que strings, caracteres e texto de fórmulas mantêm o comportamento UTF-16; o código do aplicativo pode usar seu modo Pascal preferido

Detalhes de compatibilidade

• O pacote de runtime requer Windows e LCL; o TDataToXLS exporta datasets LCL e o TGridToXLS exporta um TDBGrid, com ou sem colunas explícitas, enquanto Linux, macOS, formulários de demonstração VCL, o visualizador de pastas de trabalho VCL e o adaptador de grade DevExpress ficam fora deste pacote
• Os streams de ZIP e de compressão usam o backend Pascal empacotado e não requerem uma DLL zlib separada
• O AES usa um backend Pascal para ambas as arquiteturas, incluindo arquivos XLSX protegidos por senha
• O PNG preserva o alfa, o EMF usa gravação e reprodução de metarquivos do Windows, e o TIFF multipágina usa o runtime GDI+ do Windows
• A leitura direta de texto aceita UTF-8 e UTF-16/UTF-32 com BOM, lida com entrada em stream e mantém a propriedade do stream com o chamador
• Inicialize TXlsCsvImportOptions com TXlsCsvImportOptions.Default antes de alterar campos individuais
• As expressões de relatório e os padrões de importação do FPC usam a sintaxe Unicode de URegExpr, e não o backend PCRE do Delphi. A entrada vazia recebe a mesma resposta que TRegEx dá: um padrão que aceita string vazia, como ^$ ou .*, a corresponde, enquanto [0-9]+ não corresponde, e substituir uma string vazia produz o texto de substituição apenas quando o padrão a aceita; padrões sem suporte e padrões vazios geram ERegularExpressionError, que as expressões de relatório expõem como REPORT_EXPRESSION_INVALID_REGEX