HotXLS Docs

Обзор

HotXLS Logo
HotXLS Excel Read/Write Library — это высокопроизводительный компонент чтения и записи Excel для Delphi и C++Builder Он позволяет создавать новые электронные таблицы Excel, а также читать и изменять существующие книги XLS и XLSX без необходимости установки Microsoft Excel или Office на компьютере
HotXLS написан полностью на Object Pascal. Он читает и записывает файлы Excel напрямую на уровне двоичного кода и OOXML, поэтому отсутствуют накладные расходы COM/OLE-автоматизации и зависимость от наличия и лицензирования Office. HotXLS поддерживает Delphi и C++Builder XE5 вплоть до 13 Florence
Цветовое форматирование классического XLS намеренно остаётся палитро-ориентированным. Подробнее о решении, касающемся ThemeColor / TintAndShade, см. в разделе Классическая цветовая модель XLS

Двухфасадная архитектура

HotXLS предоставляет два сосуществующих фасадных модуля, позволяющих унаследованному коду XLS и новому коду XLSX существовать бок о бок без какого-либо рефакторинга:
lxHandle Основной фасад для формата Excel 97–2003 BIFF8 (.xls), а также экспорта в HTML, RTF, CSV и TSV Весь существующий пользовательский код продолжает использовать этот модуль без изменений. Точки входа: TXLSWorkbook, TXLSWorksheet, IXLSWorkbook, IXLSRange
lxHandleX Основной фасад для формата Excel 2007+ OOXML (.xlsx) и чтения/записи OpenDocument Spreadsheet (.ods). Предоставляет собственные типы книг и листов, поэтому поведение, специфичное для XLSX, не переносится на путь кода BIFF. Точки входа: TXLSXWorkbook, TXLSXWorksheet, TXLSXCell
Оба фасада совместно используют один и тот же механизм формул, один и тот же уровень поддержки Unicode и один и тот же конвейер экспорта Полная иерархия классов, предоставляемая lxHandleX, описана в разделе Обзор фасада XLSX

Быстрый старт

Следующие фрагменты кода демонстрируют минимальный код для создания книги с одним листом и записи значения в ячейку.

Классический XLS (lxHandle)

uses lxHandle;

var
  Book: IXLSWorkbook;
  ws:   TXLSWorksheet;
begin
  Book := TXLSWorkbook.Create;
  // Добавить лист и задать ему имя
  ws := Book.Sheets.Add;
  ws.Name := 'Sheet1';

  // Записать значения в ячейки с использованием нотации A1
  ws.Range['A1'].Value := 'Hello';
  ws.Range['B1'].Value := 42;
  ws.Range['C1'].Formula := '=B1*2';

  // Применить базовое форматирование
  ws.Range['A1'].Font.Bold := True;
  ws.Range['A1'].Interior.Color := clYellow;

  Book.SaveAs('output.xls');
end;

XLSX (lxHandleX)

uses lxHandleX;

var
  Book: TXLSXWorkbook;
  ws:   TXLSXWorksheet;
  cell: TXLSXCell;
begin
  Book := TXLSXWorkbook.Create;
  try
    ws := Book.Sheets.Add('Sheet1');

    // Записать строку и числовое значение
    ws.Cells[1, 1].Value := 'Product';
    ws.Cells[1, 2].Value := 'Price';
    ws.Cells[2, 1].Value := 'Widget';
    ws.Cells[2, 2].Value := 9.99;

    // Применить числовой формат валюты
    cell := ws.Cells[2, 2];
    cell.NumberFormat := '$#,##0.00';

    Book.SaveAs('output.xlsx');
  finally
    Book.Free;
  end;
end;
Более подробное руководство, охватывающее оба фасада в рамках одного демонстрационного проекта, см. в разделе Демонстрация API Tour

Возможности

Ввод/вывод файлов и поддержка потоков

Чтение существующих файлов Excel, запись новых или существующих файлов Excel, работа с парольной защитой классического XLS и рабочими процессами сохранения с шифрованием XLSX, а также быстрое получение списка имён листов из файлов и потоков XLS и XLSX без загрузки всей книги. Открытие CSV-файла в качестве книги поддерживается через IXLSWorkbook.OpenCSV

Значения ячеек и формулы

Чтение и запись значений ячеек всех встроенных типов Excel: число, строка, дата/время, логическое значение и формула Встроенный вычислительный механизм вычисляет формулы как в классических книгах XLS, так и в книгах XLSX, поддерживая:
  • Текстовые функции (LEFT, MID, TRIM, SUBSTITUTE, …)
  • Функции дат и рабочих дней (DATE, NETWORKDAYS, WORKDAY, …)
  • Инженерные функции и функции преобразования систем счисления (BIN2DEC, HEX2DEC, …)
  • Побитовые функции (BITAND, BITOR, BITXOR, …)
  • Статистические и агрегирующие функции (AVERAGE, SUMIF, COUNTIFS, …)
  • Математические функции (ROUND, MOD, POWER, …)
Обратный вызов OnUserFunction позволяет обрабатывать пользовательские или неподдерживаемые функции листа во время выполнения Сигнатура и примеры приведены в разделе Обратный вызов OnUserFunction
Пример вычисления формулы

Форматирование ячеек

Полный доступ к атрибутам внешнего вида ячейки:
  • Шрифты — название, размер, цвет (RGB или тематический цвет + тон), полужирный, курсив, подчёркивание, зачёркивание, верхний индекс, нижний индекс, тень и контур
  • Выравнивание — горизонтальное и вертикальное выравнивание, ориентация текста (угол), уровень отступа, перенос текста, автоподбор ширины и порядок чтения (RTL/LTR)
  • Границы — все четыре стороны и диагонали, стиль линии, толщина и цвет RGB / тематический цвет
  • Заливка — сплошная заливка, узорные заливки, цвета переднего и заднего плана, включая тематический цвет с TintAndShade
  • Числовые форматы — встроенные и пользовательские строки форматов для даты, времени, валюты, процентов и экспоненциальной записи
  • Комментарии / аннотации — добавление, чтение и оформление комментариев к ячейкам

Операции с диапазонами

IXLSRange (классический фасад) и TXLSXRange (фасад XLSX) предоставляют богатый набор операций с диапазонами:
  • Объединение и разъединение ячеек; доступ к объединённой области любой ячейки
  • Копирование, перемещение, вставка и удаление диапазонов с управлением направлением сдвига
  • Группировка и разгруппировка строк или столбцов для представлений структуры/свёртывания
  • Автоподбор высоты строки и ширины столбца по содержимому ячейки
  • Применение встроенных именованных стилей ячеек (ApplyBuiltinStyle)
  • Выделение нескольких областей (TXLSWorksheet.SelectAreas)
  • Обратный вызов итерации ForEachCell для пакетной обработки ячеек

Функции листа

Управление на уровне листа охватывает:
  • Имя листа, цвет вкладки, видимость (скрытый / очень скрытый) и навигация по индексу
  • Защита листа с детальным управлением разрешениями; защита на уровне книги
  • Закрепление областей, разделение областей и положение прокрутки
  • Диапазоны автофильтра с критериями; правила проверки данных списка
  • Условное форматирование: цветовые шкалы (2 и 3 цвета), гистограммы и наборы значков
  • Поиск и замена текста на листе
  • Параметры вида: цвет линий сетки, режим отображения формул, отображение нулей, отображение заголовков, отображение справа налево, отображение символов структуры и масштаб
  • Структурированные таблицы (TXLSTable / TXLSXTable): добавление, доступ и оформление таблиц Excel со строками заголовков и чередующимися строками
  • Диаграммы: добавление листов диаграмм и встроенных диаграмм через TXLSWorksheetsAddChartSheet и TXLSXChart

Гиперссылки и именованные диапазоны

Добавление и чтение гиперссылок (URL, mailto и внутренние ссылки на ячейки книги) через IXLSHyperLinks. Определение и разрешение именованных диапазонов на уровне книги и листа через IXLSNames / TXLSXDefinedNames. Именованные диапазоны можно использовать в формулах и преобразовывать обратно в диапазон ячеек через RefersToRange

Изображения и фигуры

Внедрение растровых изображений (BMP, JPG, PNG, GIF) в листы через TXLSShapes.AddPicture / TXLSXWorksheet.AddImage. Создание отдельных текстовых полей в классическом XLS через TXLSShapes.AddTextBox. Сохранение правил соединительных линий и решателей OfficeArt, созданных Excel, в рисунках BIFF8 и предоставление необработанных параметров FOPT фигур через TXLSShape.OfficeArtOptions для экспертных рабочих процессов рисования

Параметры страницы и печать

Полный доступ к макету печати через IXLSPageSetup:
  • Размер бумаги (A4, Letter, Legal и многие другие; см. PaperSize)
  • Ориентация (книжная / альбомная), поля, центрирование по горизонтали / вертикали
  • Строки верхнего и нижнего колонтитулов с кодами форматирования Excel (полужирный, курсив, номер страницы, дата и т. д.; см. Коды форматирования верхнего/нижнего колонтитула)
  • Ручные горизонтальные и вертикальные разрывы страниц
  • Масштабирование по числу страниц; процент масштаба; область печати; заголовки печати (повторение строк / столбцов)
  • Черновое качество; чёрно-белая печать; печать линий сетки; печать заголовков; печать примечаний

Форматы экспорта

Экспорт целых книг, отдельных листов или произвольных диапазонов ячеек в:
  • HTML — полный документ или встроенный фрагмент таблицы для предварительного просмотра или рабочих процессов электронной почты; управляется через TXLSHTMLExport и TXLSXHtmlExportOptions
  • RTF — форматированный текст для импорта в текстовый процессор
  • CSV — значения, разделённые запятыми, с настраиваемым разделителем и кодировкой
  • TSV — значения, разделённые табуляцией
  • ODS — OpenDocument Spreadsheet через фасад lxHandleX

Экспорт баз данных и сеток

Экспорт любого набора данных, совместимого с TDataSet, или TDBGrid непосредственно в Excel, HTML или RTF с помощью компонентов TDataToXLS или TGridToXLS Оба компонента генерируют события AfterCell, AfterRow, AfterTitle и AfterGroup для детального управления выводом и поддерживают многоуровневые поля группировки

Сохранение проекта VBA

HotXLS сохраняет полезные данные проекта VBA при циклической обработке книг с поддержкой макросов. Просмотр модулей в режиме только для чтения доступен через TXLSVBAProject и TXLSVBAModule Используйте IXLSWorkbook.HasVBAProject для обнаружения полезных данных и LoadVBAProjectFromFile / SaveVBAProjectToFile для переноса между файлами

Unicode и международный текст

Все операции со строками являются нативно-юникодными. HotXLS читает и записывает файлы Excel, созданные на любом языке, включая CJK, арабский, иврит, тайский и другие письменности, с правильным поддержкой двунаправленного текста и порядка чтения
Пример поддержки символов Unicode

Сводные таблицы (классический XLS)

Создание сводных таблиц из исходного диапазона с помощью TXLSWorksheet.AddPivotTable, настройка размещения полей и числовых форматов полей данных, а также проверка модели сводной таблицы через TXLSWorksheet.PivotTables Подробнее о полях и фильтрах см. в разделе API сводных таблиц классического XLS

Преимущества

No Office dependency Читает и записывает файлы XLS и XLSX напрямую на двоичном уровне. Microsoft Excel или Office не нужно устанавливать, лицензировать или запускать. Это устраняет накладные расходы COM/OLE-автоматизации, позволяет избежать ограничений многопоточности, налагаемых взаимодействием с Office, и позволяет использовать HotXLS в серверных и служебных контекстах, где установка настольного Office неудобна
High performance Парсеры BIFF8 и OOXML написаны на нативном Object Pascal без промежуточного выделения DOM XML для горячего пути. Большие книги с сотнями тысяч строк можно читать и записывать с низким пиковым потреблением памяти Дедупликация общих строк и сжатие общих формул применяются автоматически для поддержания небольшого размера файлов
OLE migration path Поверхность API классического фасада (книга, лист, диапазон, шрифт, границы, заливка, параметры страницы) точно отражает объектную модель Excel, привычную по OLE-автоматизации. Это делает миграцию существующих проектов на основе OLE простой: заменить вызовы COM на вызовы HotXLS, устранить зависимость от Office и получить нативную производительность
Dual-facade design Унаследованный код XLS продолжает компилироваться и работать без изменений через lxHandle, тогда как новый код XLSX использует более богатый фасад lxHandleX. Поэтапная миграция одного формата файла является безопасной и постепенной
Formula engine included Встроенный многопроходный вычислительный механизм обрабатывает наиболее распространённые функции листа без необходимости пересчёта Excel при открытии. Пользовательские функции обрабатываются через обратный вызов OnUserFunction
Easy to use Компоненты Delphi для подключаемого использования (TDataToXLS, TGridToXLS) не требуют написания кода для стандартных задач экспорта. API гибкого диапазона поддерживает нотацию A1, нотацию R1C1 и индексирование строк/столбцов с отсчётом от нуля
Thread-safe file I/O Поскольку общий процесс Office отсутствует, несколько экземпляров TXLSXWorkbook могут создаваться и сохраняться одновременно в независимых потоках без синхронизации, что делает HotXLS подходящим для многопоточных серверов генерации отчётов

Совместимость

HotXLS совместим со следующими версиями RAD Studio:
Delphi XE5, XE6, XE7, XE8, 10 Seattle, 10.1 Berlin, 10.2 Tokyo, 10.3 Rio, 10.4 Sydney, 11 Alexandria, 12 Athens, 13 Florence
C++Builder XE5, XE6, XE7, XE8, 10 Seattle, 10.1 Berlin, 10.2 Tokyo, 10.3 Rio, 10.4 Sydney, 11 Alexandria, 12 Athens, 13 Florence
Target platforms Windows 32-бит и 64-бит
Excel file formats XLS (BIFF8, Excel 97–2003), XLSX (OOXML, Excel 2007+), ODS (OpenDocument 1.2)
Export-only formats HTML, RTF, CSV, TSV

См. также