Поддержка Free Pascal и Lazarus

HotXLS поддерживает Free Pascal 3.2.2 с Lazarus/LCL на Windows Win32 и Win64, включая API книг XLS/XLSX, формулы, форматирование, прямой стриминг, компоненты экспорта TDataToXLS и TGridToXLS и вспомогательные модули рендеринга

Нативное ядро книг для Linux и macOS

API каталогов с ограниченной областью действия, явное владение нативным хранилищем, метки времени и канонические ключи идентификаторов Classic описаны в разделе хранилища составных файлов

Включаемый по выбору профиль LX_PORTABLE_CORE открывает TXLSWorkbook и TXLSXWorkbook без LCL на Linux и macOS. Нативные Linux x64 и macOS ARM64 были скомпилированы и выполнены с Free Pascal 3.3.1; защитная проверка версии исходников требует минимум 3.2.2, но этот минимум не является утверждением, что каждая комбинация нативного компилятора и цели проверена

Поместите cthreads и cwstring перед модулями HotXLS, добавьте Lib в пути поиска модулей и include, а LX_PORTABLE_CORE определите для всей сборки. Нативному консольному приложению не нужны Interfaces или виджетсет LCL

Выбирайте установленную UTF-8 локаль в окружении приложения при работе с путями файловой системы в Unicode. Недопустимая или не-UTF-8 локаль может сделать преобразование имён файлов в нативной RTL с потерями; помощник валидации явно отклоняет такое окружение вместо смены локали или угадывания кодовой страницы

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.

Методы открытия и сохранения сохраняют свои обычные контракты кодов результата и диагностики. Прямые вызовы на платформенных границах могут возбудить EXLSPlatformUnsupported; обрабатывайте это исключение при вызове службы, доступной только в Windows, из общего кода приложения

Воспроизводимая нативная валидация

Запустите помощник валидации на нативном госте с имеющимся тулчейном Free Pascal, Python 3 и нативным C-компилятором. Выберите новый или пустой выходной каталог вне checkout исходников в файловой системе гостя

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

Помощник копирует и хеширует исходные входы, нормализует имена файлов модулей Pascal в приватной копии сборки для чувствительного к регистру поиска имён файлов FPC, собирает PCRE2 локально и запускает свидетелей ядра, AES, сжатия, REGEX, публичных книг и интеграции. Он сохраняет манифесты исходников, журналы компилятора, артефакты и сбои, не меняя checkout, не устанавливая инструменты и не редактируя конфигурацию компилятора. Сборки macOS ARM64 явно нацелены на macOS 11 или новее

Свидетели интеграции включают пути в Unicode, фикстуры XLSB, созданные Excel, кэши формул и пересчёт, повторные открытия, разреженные ODS-примечания и защиту, отклонение проверенной конвертации, отмену с сохранением приёмников вызывающего, инвариантный поиск имён с областью действия, локализацию сбоев настоящих рабочих потоков и криптографические случайные байты

Нативные контракты Classic XLS

Используйте lxHandle для классического TXLSWorkbook и lxHandleX для TXLSXWorkbook. Классический Recalculate возвращает количество ошибок, поэтому ноль означает успех; его метод Calculate возвращает результат формулы. Присвоения Formula классической ячейки требуют ведущего =. Методы открытия и сохранения книги сохраняют установленный успешный результат 1

Нативная реализация классического хранилища использует настоящую иерархию составного файла и идентичности потоков, сохраняя вложенные области, данные MiniFAT и расширенные цепочки DIFAT. Полезные нагрузки потоков материализуются, а писатель отклоняет агрегированный вывод за пределами поддерживаемых знаковых 32-битных границ буфера/секторов до его выдачи; это не реализация потокового хранилища на многие гигабайты

Нативное составное хранилище предоставляет прямые операции с потоками, перечисление, метаданные и операции копирования. Откат транзакции, блокировка областей, перемещение и неподдерживаемые режимы исключения возвращают явные ошибки хранилища. Оно не эмулирует службы Windows COM, буфера обмена или GDI

Нативное сохранение классического файла сериализует данные до атомарной замены зарегистрированного соседнего файла. Сохранение в поток вызывающего подготавливает полный составной файл до копирования на исходной позиции, сохраняя префиксы и сбои отмены до фиксации. Финальное уведомление о ходе выполнения остаётся неотменяемым. Прямые записи помощника составного хранилища следуют своему обычному контракту прямой записи, а не публичной транзакции сохранения книги

Обычные свойства summary и document-summary используют ограниченные стандартные наборы свойств OLE с текстом Unicode и метками времени UTC FILETIME. Эти потоки свойств остаются в открытом виде, когда данные классической книги зашифрованы, и заголовок RC4 CryptoAPI явно фиксирует этот выбор. Определённые имена разделяют закреплённые канонические ключи идентификаторов, используемые фасадом XLSX, сохраняя исходное написание и явную область листа. Закодированные данные рисунков PNG/JPEG остаются доступны модели; нативная конвертация растровых изображений/метафайлов требует отдельного поддерживаемого рендерера, иначе возбуждается EXLSPlatformUnsupported

Скомпилируйте Tests/Lazarus/HotXLSNativeClassicWorkbookSmoke.lpr с теми же опциями нативного ядра, затем передайте Tests/Fixtures/classic-native/native-classic.xls, одноразовый гостевой локальный путь вывода и Tests/Fixtures/classic-native/native-classic-encrypted.xls. Контрольные проверки покрывают кэши, созданные Excel, пересчёт, точные имена Unicode, обычные и зашифрованные круговые преобразования, независимо декодируемые метки времени свойств, повторные открытия, более 16 МБ данных SST и сохранение вывода вызывающего

Байтовое кодирование устаревшего BIFF

TXLSWorkbook.SetCodePage выбирает явную байтовую кодировку, используемую SaveAs(..., xlExcel5), по умолчанию CP1252; импорт файла BIFF2–BIFF5 с пригодной ненулевой записью CODEPAGE также выбирает эту страницу для последующих устаревших сохранений

Устаревшие подписи ячеек, текстовые константы и массивы формул, кэшированные строки формул, определённые имена, имена и ссылки листов, имена шрифтов, числовые форматы, имена стилей, колонтитулы и обычный текст примечаний используют объявленную страницу, а не локаль операционной системы или UTF-8

Длины записей и смещения потока листа считают закодированные байты; существующие 255-байтовые лимиты устаревших подписей и литералов формул усекаются только на границе целого символа, поэтому двухбайтовый символ CP932 никогда не разрезается; имена и метаданные с однобайтовой длиной отклоняют закодированный текст длиннее представимого, вместо выдачи недопустимой длины

Текст, который не может пройти круговое преобразование через выбранную кодовую страницу, возбуждает EConvertError прежде, чем молча превратиться в символ замены или наилучшего соответствия; выберите страницу, представляющую текст документа, или сохраняйте как BIFF8 для строк Unicode

Строки кэша формул, пересекающие записи CONTINUE, собираются как байты до декодирования, поэтому граница записи может разрезать двухбайтовый символ, не повреждая кэшированное значение

Смена выбранной страницы перестраивает типизированные байты устаревших формул и определённых имён из их модели Unicode; сохранения BIFF8 продолжают использовать Unicode, а их значение CODEPAGE на диске остаётся 1200

Импортированные записи диаграмм BIFF5 сохраняют свою исходную кодовую страницу для типизированного осмотра серий и присоединённых заголовков, в том числе после правки кодовой страницы книги или копирования диаграммы; сохранение на другую страницу явно перекодирует поддерживаемые SeriesText, обычные кэшированные подписи и строки формул, колонтитулы и имена внешних листов текущей книги, а не переинтерпретирует сохранённые байты под новым объявлением

Продолженный текст диаграмм, немоделированные устаревшие кодировки внешних листов и непрозрачные устаревшие записи байтового текста отклоняют миграцию кодовой страницы с EConvertError; непредставимый поддерживаемый текст также отклоняется, а публичное сохранение книги сохраняет приёмник вызывающего до фиксации; этот текстовый контракт не обещает полную конвертацию внешнего вида нативных диаграмм

Пользовательские имена стилей BIFF5 начинаются сразу после однобайтовой закодированной длины, при этом BIFF5 SeriesText имеет идентификатор и однобайтовую закодированную длину без флага Unicode; BIFF8 SeriesText добавляет свой флаг Unicode, а конвертация поддерживаемого текста диаграмм обновляет эту запись и версию BOF диаграммы вместе

Непустые колонтитулы диаграмм BIFF5 используют однобайтовую закодированную длину с максимумом 255 байтов; кэшированные записи LABEL и STRING используют двухбайтовые длины, тогда как колонтитулы BIFF8 используют двухбайтовую длину UTF-16 плюс свой флаг Unicode; миграция проверяет фактическую структуру каждой записи и отклоняет слишком большой устаревший колонтитул с ERangeError до его добавления

HotXLS интерпретирует устаревшие байты по их объявленной странице на Windows, Linux и macOS; установленный Excel 16.0 build 20430 независимо продемонстрировал ограничение получателя: он интерпретировал устаревшие байты по своей локальной Windows CP936, даже когда только запись CODEPAGE нативного файла менялась на CP1252 или CP932, поэтому корректные объявленные байты не гарантируют совпадающий текст в этой конфигурации получателя

Сохраняйте фактическое объявление кодировки документа и проверяйте принимающее приложение при распространении BIFF5 между разными конфигурациями локалей; Unicode BIFF8 избегает этой конкретной границы совместимости устаревших байтов

Это исправление байтового кодирования сохраняет существующий лимит размера записи обычных примечаний BIFF5; оно не добавляет в устаревшую запись поля автора примечания, rich-text форматирования или геометрии фигур

Редактирование исходного кода модулей VBA использует объявленную байтовую кодовую страницу проекта и сохраняет бинарный префикс до смещения исходника, включая встроенные нулевые байты; это меняет сохранённый текст исходника и не выполняет макросы

Сжатый Unicode BIFF8 с fHighByte = 0 отображает каждый байт напрямую в кодовую единицу UTF-16 от U+0000 до U+00FF; это не CP1252, не UTF-8 и не устаревшая кодовая страница файла, даже когда нестандартная запись CODEPAGE появляется в файле, во всём остальном являющемся BIFF8

Нативные текстовые формулы сохраняют длины и позиции UTF-16, включая кодовые единицы суррогатных пар; Unicode-функции LOWER, UPPER, SEARCH, регистронезависимые разделители TEXTBEFORE/TEXTAFTER, заголовки полей баз данных, регистронезависимые критерии и динамические текстовые ключи используют Unicode-данные символов нативного компилятора, а не ASCII-only функции регистра локали C хоста, при этом обычное упорядочивание листа сохраняет существующее сравнение по локали

Сопоставление локальных имён LET/LAMBDA и классификация хранения локальных массивов на нативе используют тот же учёт регистра в Unicode, поэтому регистровые пары разрешают правильную захваченную привязку и сохраняют её форму массива; это не меняет закреплённый публичный контракт идентичности определённых имён

Классические регистронезависимые FindText и ReplaceText сохраняют сопоставление символов Unicode для литерального поиска и поиска с подстановочными знаками Excel на нативном FPC; MatchCase по-прежнему различает регистр, литеральная замена сохраняет поведение замены всех вхождений, замена с подстановочными знаками сохраняет существующее поведение самого левого охвата, а ячейки с формулами остаются исключёнными

Скомпилируйте Tests/Lazarus/HotXLSNativeLegacyEncodingSmoke.lpr с опциями нативного ядра и передайте одноразовый выходной каталог, затем Tests/Fixtures/legacy-encoding/native-biff5-cp936-chart.xls; свидетель проверяет независимо объявленные байты CP1252, CP932 и CP936, каждое смещение листа, смены кодовой страницы, границы продолжения двухбайтовых символов, импорт сжатого BIFF8, вычисление формул, текст диаграмм нативного автора и сохранение приёмника при сбое сохранения

Полный установщик

Полный установщик обнаруживает Lazarus и поддерживает установку без RAD Studio. Выберите Lazarus / Free Pascal на странице интеграции с IDE, чтобы установить пакет времени выполнения, модули совместимости и скрипты сборки; эта опция выбрана по умолчанию, когда Lazarus — единственная обнаруженная IDE

На странице пост-установочной компиляции выберите пакет времени выполнения Free Pascal для Win32 или Win64. Цель доступна, когда обнаружены её компилятор, RTL, LCL и модули LazUtils; исходники пакета можно установить, даже если цель недоступна, и скомпилировать их позже

Пакет содержит только время выполнения и добавляется как зависимость проекта в Lazarus. Установщик не компилирует VCL-демонстрации с помощью Free Pascal

Сборка и тестирование

Откройте Lib/FPC/HotXLSLaz.lpk в Lazarus и скомпилируйте пакет времени выполнения или выполните эти команды из каталога HotXLS

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

Задайте LAZARUS_DIR для выбора установки; FPC_EXE и LAZBUILD_EXE могут при необходимости указать явные исполняемые файлы компилятора и сборщика пакетов

Выбранная установка должна содержать FPC и скомпилированные модули LCL/LazUtils для целевой архитектуры; выходные данные и конфигурация сборщика пакетов хранятся в отдельных каталогах для каждой архитектуры

Настройка приложения

Добавьте Lib и Lib/FPC в путь поиска модулей, а Lib — в путь поиска include или добавьте пакет времени выполнения как зависимость проекта Lazarus

Поместите Interfaces перед модулями HotXLS в списке uses приложения, включая консольные приложения; это инициализирует виджетсет LCL и преобразование UTF-8 на границах 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.

Исходные модули HotXLS внутренне выбирают семантику Unicode Delphi, поэтому строки, символы и текст формул сохраняют поведение UTF-16; код приложения может использовать предпочитаемый режим Pascal

Детали совместимости

• Пакет времени выполнения требует Windows и LCL; TDataToXLS экспортирует наборы данных LCL, а TGridToXLS экспортирует TDBGrid, с явными столбцами или без них, тогда как Linux, macOS, демонстрационные формы VCL, просмотрщик книг VCL и адаптер сетки DevExpress находятся вне этого пакета
• Потоки ZIP и сжатия используют встроенный бэкенд на Pascal и не требуют отдельного zlib DLL
• AES использует бэкенд на Pascal для обеих архитектур, включая защищённые паролем файлы XLSX
• PNG сохраняет альфа-канал, EMF использует запись и воспроизведение метафайлов Windows, а многостраничный TIFF — среду выполнения GDI+ Windows
• Прямое чтение текста принимает UTF-8 и UTF-16/UTF-32 с BOM, обрабатывает потоковый ввод и оставляет владение потоком вызывающему
• Инициализируйте TXlsCsvImportOptions значением TXlsCsvImportOptions.Default перед изменением отдельных полей
• Выражения отчётов и шаблоны импорта FPC используют синтаксис Unicode URegExpr, а не бэкенд PCRE Delphi. Пустой ввод получает тот же ответ, что и TRegEx: шаблон, допускающий пустую строку, например ^$ или .*, совпадает с ней, тогда как [0-9]+ — нет, а замена пустой строки даёт замещающий текст, только если шаблон её допускает; неподдерживаемые и пустые шаблоны вызывают ERegularExpressionError, который выражения отчётов раскрывают как REPORT_EXPRESSION_INVALID_REGEX