Documentación de HotXLS

Soporte de Free Pascal y Lazarus

HotXLS brinda soporte para Free Pascal 3.2.2 con Lazarus/LCL en Windows Win32 y Win64, incluidas las API de libros de trabajo XLS/XLSX, las fórmulas, el formato, la lectura y escritura directa en streaming, los componentes de exportación TDataToXLS y TGridToXLS y las utilidades de renderizado

Núcleo nativo de libros para Linux y macOS

Consulte el almacenamiento de archivos compuestos para las API de directorios con ámbito, la propiedad explícita del almacenamiento nativo, las marcas de tiempo y las claves canónicas de identificadores Classic

El perfil opcional LX_PORTABLE_CORE expone TXLSWorkbook y TXLSXWorkbook sin LCL en Linux y macOS. Linux x64 nativo y macOS ARM64 se han compilado y ejecutado con Free Pascal 3.3.1; el guard de versión del código fuente exige al menos 3.2.2, pero ese mínimo no afirma que se haya validado cada combinación de compilador y destino nativos

Coloque cthreads y cwstring antes de las unidades de HotXLS, agregue Lib a las rutas de unidades e inclusiones y defina LX_PORTABLE_CORE para toda la compilación. Una aplicación de consola nativa no requiere Interfaces ni un widgetset de la LCL

Elija una configuración regional UTF-8 instalada en el entorno de la aplicación cuando trabaje con rutas de archivos Unicode. Una configuración regional inválida o que no sea UTF-8 puede volver con pérdidas la conversión de nombres de archivo del RTL nativo; el helper de validación rechaza ese entorno de forma explícita en lugar de cambiar la configuración regional o adivinar una página de códigos

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.
ÁreaContrato del núcleo nativo
Archivos de libroCrear, abrir, editar, calcular y guardar XLS Classic BIFF8, XLSX, el subconjunto XLSB expandido soportado y el subconjunto ODS soportado a través de las API públicas de libros, con sus comprobaciones de conversión y límites de formato existentes. Los registros BIFF2 Classic con codificaciones CP1252 y CP932 declaradas explícitamente también se han validado mediante importación y exportación Unicode BIFF8
Unicode y nombresEl texto del libro conserva la semántica UTF-16 y las rutas del sistema de archivos usan UTF-8 en las fronteras nativas. La identidad de los nombres definidos usa la normalización canónica Unicode 16 fijada y el plegado de mayúsculas completo del BMP, preservando símbolos, acentos, distinciones del turco e identidad de mayúsculas astrales con independencia de la configuración regional del host; las fórmulas calificadas conservan su ámbito exacto de hoja. La ordenación ordinaria del texto de las hojas sigue usando la comparación regional del RTL nativo
InfraestructuraSe usan secciones críticas nativas, identificadores de hilo de ancho completo, hilos de trabajo reales, archivos temporales exclusivos registrados, reemplazo atómico de archivos hermanos y bytes aleatorios del sistema operativo, sin emulación de Windows
Compresión y criptografíaEl ZIP/compresión de Pascal incluido y AES siguen disponibles. Los archivos XLS con RC4 Classic y RC4 CryptoAPI se pueden leer y escribir de forma nativa usando bytes aleatorios del sistema operativo. La lectura nativa de OOXML cifrado usa el reader puro de archivos compuestos; escribir un archivo compuesto OOXML cifrado requiere Windows y lanza una excepción explícita de plataforma en Unix nativo
Funciones REGEX de fórmulaEl backend estático fijado de PCRE2 en UTF-16 se compila en el destino nativo con su compilador de C. Ejecute sh Lib/thirdparty/build-pcre2-unix.sh antes de compilar aplicaciones que incluyan el motor de fórmulas; se proveen destinos estáticos para Linux x64 y macOS ARM64
Servicios de WindowsEl acceso al portapapeles, la activación COM de Windows, los proveedores de consulta integrados de ADO/WinHTTP, la captura de geometría GDI, la decodificación de imágenes de fondo HTML y la exportación heredada de PDF lanzan EXLSPlatformUnsupported en sus fronteras explícitas. Los proveedores personalizados de consulta y de texto siguen siendo utilizables
Componentes heredadosEl modelo de libro Classic y el lector/escritor BIFF están disponibles en el núcleo nativo. El paquete de runtime de la LCL, los componentes de exportación de datasets/cuadrículas y los controles visuales siguen siendo componentes de Windows/LCL. Los métodos heredados de portapapeles, la exportación HTML y la exportación heredada de PDF lanzan excepciones explícitas de plataforma en Unix nativo
Fórmulas de texto orientadas a bytesLas funciones que dependen de la página de códigos ANSI/DBCS activa de Windows devuelven un resultado de fórmula explícitamente no soportado (#NAME?) en Unix nativo; no se elige ningún sustituto implícito de configuración regional o página de códigos

Los métodos de apertura y guardado conservan sus contratos normales de códigos de resultado y diagnósticos. Las llamadas directas a fronteras de plataforma pueden lanzar EXLSPlatformUnsupported; maneje esta excepción al invocar un servicio exclusivo de Windows desde código compartido de la aplicación

Validación nativa reproducible

Ejecute el helper de validación en el invitado nativo con un conjunto de herramientas de Free Pascal existente, Python 3 y un compilador de C nativo. Elija un directorio de salida nuevo o vacío fuera del checkout del código fuente, en el sistema de archivos del invitado

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

El helper copia y hashea las entradas del código fuente, normaliza los nombres de archivo de las unidades Pascal en la copia privada de compilación para la búsqueda sensible a mayúsculas de FPC, compila PCRE2 localmente y ejecuta los tests de núcleo, AES, compresión, REGEX, libro público e integración. Preserva los manifiestos del código fuente, los registros del compilador, los artefactos y los fallos sin cambiar el checkout, sin instalar herramientas ni editar la configuración del compilador. Las compilaciones de macOS ARM64 apuntan explícitamente a macOS 11 o posterior

Los tests de integración incluyen rutas Unicode, fixtures XLSB creados por Excel, cachés de fórmulas y recálculo, aperturas repetidas, notas dispersas de ODS y protección, rechazo de conversión verificado, cancelación que preserva los destinos del llamador, búsqueda invariante de nombres con ámbito, contención real de fallos de hilos de trabajo y bytes aleatorios criptográficos

Contratos del XLS Classic nativo

Use lxHandle para el TXLSWorkbook Classic y lxHandleX para el TXLSXWorkbook. El Recalculate Classic devuelve un conteo de errores, así que cero significa éxito; su método Calculate devuelve un resultado de fórmula. Las asignaciones de Formula de celda Classic exigen un = inicial. Los métodos de apertura y guardado del libro mantienen su resultado de éxito establecido de 1

La implementación nativa del almacenamiento Classic usa una jerarquía real de archivos compuestos e identidades de flujos, preservando ámbitos anidados, datos MiniFAT y cadenas DIFAT extendidas. Las cargas útiles de los flujos se materializan y el escritor rechaza una salida agregada que supere sus límites soportados de buffer/sector con signo de 32 bits antes de emitirla; no es una implementación de almacenamiento en streaming de múltiples gigabytes

El almacenamiento compuesto nativo proporciona operaciones directas de flujos, enumeración, metadatos y operaciones de copia. El rollback de transacciones, el bloqueo de regiones, el movimiento y los modos de exclusión no soportados devuelven errores explícitos de almacenamiento. No emula los servicios COM, portapapeles ni GDI de Windows

Los guardados nativos de archivos Classic serializan antes de reemplazar atómicamente un archivo hermano registrado. Los guardados a flujos del llamador escalonan el archivo compuesto completo antes de copiar en la posición original, preservando prefijos y fallos de cancelación antes del commit. La notificación final de progreso sigue siendo no cancelable. Las escrituras directas del helper de almacenamiento compuesto siguen su contrato ordinario de escritura directa, no la transacción pública de guardado del libro

Las propiedades ordinarias de resumen y de resumen de documento usan conjuntos de propiedades OLE estándar acotados con texto Unicode y marcas de tiempo UTC FILETIME. Estos flujos de propiedades permanecen en texto plano cuando los datos del libro Classic están cifrados, y el encabezado RC4 CryptoAPI registra esa decisión explícitamente. Los nombres definidos comparten las claves canónicas de identificador fijadas que usa la fachada XLSX, conservando su ortografía original y su ámbito explícito de hoja. Los datos codificados PNG/JPEG de dibujo siguen disponibles para el modelo; la conversión nativa de bitmap/metafile exige un renderer soportado aparte y de lo contrario lanza EXLSPlatformUnsupported

Compile Tests/Lazarus/HotXLSNativeClassicWorkbookSmoke.lpr con las mismas opciones del núcleo nativo y luego pase Tests/Fixtures/classic-native/native-classic.xls, una ruta de salida desechable local del invitado y Tests/Fixtures/classic-native/native-classic-encrypted.xls. Los controles cubren cachés creadas por Excel, recálculo, nombres Unicode exactos, roundtrips simples y cifrados, marcas de tiempo de propiedades decodificadas de forma independiente, aperturas repetidas, más de 16 MB de datos SST y preservación de la salida del llamador

Codificación de bytes BIFF heredada

TXLSWorkbook.SetCodePage selecciona la codificación de bytes explícita que usa SaveAs(..., xlExcel5), con CP1252 por defecto; importar un archivo BIFF2–BIFF5 con un registro CODEPAGE utilizable distinto de cero también selecciona esa página para los guardados heredados posteriores

Las etiquetas de celda heredadas, las constantes de texto de fórmula y los arreglos, las cadenas de fórmula en caché, los nombres definidos, los nombres de hojas y referencias, los nombres de fuentes, los formatos numéricos, los nombres de estilos, los encabezados, los pies de página y el texto ordinario de comentarios usan esa página declarada en lugar de la configuración regional del sistema operativo o de UTF-8

Las longitudes de registro y los desplazamientos del flujo de la hoja cuentan bytes codificados; los límites heredados existentes de 255 bytes para etiquetas y literales de fórmula truncan solo en un límite de carácter completo, de modo que un carácter de doble byte CP932 nunca se parte; los nombres y metadatos con longitud de un byte rechazan texto codificado más largo que su longitud representable en lugar de emitir una longitud inválida

El texto que no pueda hacer roundtrip por la página de códigos seleccionada lanza EConvertError antes de convertirse silenciosamente en un carácter de reemplazo o de mejor ajuste; elija una página que represente el texto del documento o guarde como BIFF8 para cadenas Unicode

Las cadenas de caché de fórmulas que abarcan registros CONTINUE se ensamblan como bytes antes de decodificar, de modo que un límite de registro puede partir un carácter de doble byte sin corromper el valor en caché

Cambiar la página seleccionada reconstruye los bytes con tipos de las fórmulas heredadas y de los nombres definidos a partir de su modelo Unicode; los guardados BIFF8 siguen usando Unicode y su valor CODEPAGE en disco permanece en 1200

Los registros de gráficos BIFF5 importados conservan su página de códigos original para la inspección con tipos de series y títulos adjuntos, incluso tras una edición de la página de códigos del libro o una copia de gráfico; guardar hacia una página distinta transcodifica explícitamente el SeriesText soportado, las etiquetas planas en caché y las cadenas de fórmula, los encabezados, los pies de página y los nombres de hojas externas del libro actual, en lugar de reinterpretar bytes preservados bajo la nueva declaración

El texto de gráfico continuado, las codificaciones de hojas externas heredadas sin modelar y los registros heredados opacos de texto en bytes rechazan una migración de página de códigos con EConvertError; el texto soportado irrepresentable también se rechaza, y el guardado público del libro preserva el destino del llamador antes del commit; este contrato de texto no promete una conversión completa del aspecto nativo de los gráficos

Los nombres de estilo personalizados BIFF5 comienzan inmediatamente después de la longitud codificada de un byte, mientras que el SeriesText BIFF5 lleva un identificador y una longitud codificada de un byte sin bandera Unicode; el SeriesText BIFF8 agrega su bandera Unicode, y convertir el texto de gráfico soportado actualiza ese registro y la versión BOF del gráfico en conjunto

Los encabezados y pies de página de gráficos BIFF5 no vacíos usan una longitud codificada de un byte con un máximo de 255 bytes; los registros LABEL y STRING en caché usan longitudes de dos bytes, mientras que los encabezados y pies de página BIFF8 usan una longitud UTF-16 de dos bytes más su bandera Unicode; la migración comprueba la disposición real de cada registro y rechaza un encabezado o pie heredado demasiado grande con ERangeError antes de anexarlo

HotXLS interpreta los bytes heredados usando su página declarada en Windows, Linux y macOS; el Excel 16.0 build 20430 instalado demostró de forma independiente una limitación del destinatario: interpretó los bytes heredados con su CP936 local de Windows incluso después de que el registro CODEPAGE de un archivo nativo, por sí solo, se cambiara a CP1252 o CP932, así que unos bytes declarados correctos no garantizan texto coincidente en esa configuración del destinatario

Preserve la declaración de codificación real del documento y pruebe la aplicación receptora al distribuir BIFF5 entre distintas configuraciones regionales; el BIFF8 Unicode evita esta frontera particular de interoperabilidad de bytes heredados

Esta corrección de codificación de bytes conserva el límite existente de tamaño de registro de comentarios ordinarios BIFF5; no agrega campos de autor de comentario, formato de texto enriquecido ni geometría de forma al registro heredado

La edición del código fuente de módulos VBA usa la página de códigos de bytes declarada del proyecto y preserva el prefijo binario antes del desplazamiento del código fuente, incluidos los bytes null incrustados; esto cambia el texto del código fuente almacenado y no ejecuta macros

El Unicode comprimido BIFF8 con fHighByte = 0 mapea cada byte directamente a una unidad de código UTF-16 de U+0000 a U+00FF; no es CP1252, UTF-8 ni la página de códigos heredada del archivo, incluso cuando aparece un registro CODEPAGE no estándar en un archivo por demás BIFF8

Las fórmulas de texto nativas conservan longitudes y posiciones UTF-16, incluidas las unidades de código de pares sustitutos; el manejo de mayúsculas de Unicode en LOWER, UPPER, SEARCH, los delimitadores insensibles a mayúsculas de TEXTBEFORE/TEXTAFTER, los encabezados de campos de base de datos, los criterios insensibles a mayúsculas y las claves de texto dinámicas usan los datos de caracteres Unicode del compilador nativo en lugar de las funciones de solo ASCII de la configuración regional del C del host, mientras que la ordenación ordinaria de las hojas conserva su comparación regional existente

La coincidencia de nombres locales de LET/LAMBDA nativa y la clasificación de almacenamiento de arreglos locales usan el mismo manejo de mayúsculas consciente de Unicode, de modo que las contrapartes de mayúsculas resuelven el enlace capturado correcto y conservan su forma de arreglo; esto no cambia el contrato público fijado de identidad de nombres definidos

FindText y ReplaceText Classic insensibles a mayúsculas conservan la coincidencia de caracteres Unicode para búsquedas literales y con comodines de Excel en FPC nativo; MatchCase sigue distinguiendo mayúsculas, el reemplazo literal conserva su comportamiento de reemplazar todo, el reemplazo con comodines conserva su comportamiento existente de tramo más a la izquierda y las celdas con fórmula siguen excluidas

Compile Tests/Lazarus/HotXLSNativeLegacyEncodingSmoke.lpr con las opciones del núcleo nativo y pase un directorio de salida desechable seguido de Tests/Fixtures/legacy-encoding/native-biff5-cp936-chart.xls; el test comprueba de forma independiente los bytes CP1252, CP932 y CP936 declarados, todos los desplazamientos de las hojas, los cambios de página de códigos, los límites de continuación de doble byte, la importación BIFF8 comprimida, el cálculo de fórmulas, el texto de gráficos creado de forma nativa y la preservación del destino ante un guardado fallido

Instalador completo

El instalador completo detecta Lazarus y permite la instalación sin RAD Studio. Seleccione Lazarus / Free Pascal en la página de integración con IDE para instalar el paquete de runtime, las unidades de compatibilidad y los scripts de compilación; esta opción viene seleccionada de forma predeterminada cuando Lazarus es el único IDE detectado

En la página de compilación posterior a la instalación, seleccione el paquete de runtime de Free Pascal para Win32 o Win64. Un destino está disponible cuando se detectan su compilador, RTL, LCL y unidades LazUtils; aun cuando un destino no esté disponible puede instalar los fuentes del paquete y compilarlos después

El paquete es solo de runtime y se agrega como dependencia del proyecto en Lazarus. El instalador no compila las demos de la VCL con Free Pascal

Compilación y pruebas

Abra Lib/FPC/HotXLSLaz.lpk en Lazarus y compile el paquete de runtime, o bien ejecute estos comandos desde el directorio de HotXLS

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

Establezca LAZARUS_DIR para elegir una instalación; FPC_EXE y LAZBUILD_EXE permiten indicar ejecutables explícitos del compilador y del constructor de paquetes cuando haga falta

La instalación elegida debe contener las unidades FPC y LCL/LazUtils compiladas para la arquitectura de destino; las salidas y la configuración del constructor de paquetes se guardan en directorios separados por arquitectura

Configuración de la aplicación

Agregue Lib y Lib/FPC a la ruta de búsqueda de unidades y Lib a la ruta de búsqueda de inclusiones, o bien agregue el paquete de runtime como dependencia del proyecto de Lazarus

Coloque Interfaces antes de las unidades de HotXLS en la lista de uses de la aplicación, incluidas las aplicaciones de consola; esto inicializa el widgetset de la LCL y la conversión UTF-8 en las fronteras 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.

Las unidades de código fuente de HotXLS seleccionan internamente la semántica Unicode de Delphi, de modo que las cadenas, los caracteres y el texto de las fórmulas conservan el comportamiento UTF-16; el código de la aplicación puede usar el modo Pascal que prefiera

Detalles de compatibilidad