Документація HotXLS

Огляд

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 навмисно залишається палітровим. Дивіться Класична кольорова модель XLS для ознайомлення з рішенням щодо ThemeColor / TintAndShade

Архітектура подвійного фасаду

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 та один конвеєр експорту Дивіться Огляд фасаду XLSX для повної ієрархії класів, що надається lxHandleX

Швидкий старт

Наведені нижче фрагменти показують мінімальний код для створення робочої книги з одним аркушем та запису значення в комірку.

Класичний XLS (lxHandle)

uses lxHandle;

var
  Book: IXLSWorkbook;
  ws:   TXLSWorksheet;
begin
  Book := TXLSWorkbook.Create;
  // Add a worksheet and give it a name
  ws := Book.Sheets.Add;
  ws.Name := 'Sheet1';

  // Write values to cells using A1 notation
  ws.Range['A1'].Value := 'Hello';
  ws.Range['B1'].Value := 42;
  ws.Range['C1'].Formula := '=B1*2';

  // Apply basic formatting
  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');

    // Write a string and a numeric value
    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;

    // Apply a currency number format
    cell := ws.Cells[2, 2];
    cell.NumberFormat := '$#,##0.00';

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

Можливості

Введення/виведення файлів та підтримка потоків

Читання наявних файлів 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 для його переміщення між файлами

Юнікод та міжнародний текст

Вся обробка рядків є нативно юнікодною. 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 без проміжного виділення пам'яті під XML DOM для критичного шляху. Великі робочі книги зі сотнями тисяч рядків можна читати та записувати з низьким пиковим споживанням пам'яті. Дедублювання спільних рядків та стиснення спільних формул застосовуються автоматично для зменшення розміру файлів
OLE migration path Поверхня API класичного фасаду (робоча книга, аркуш, діапазон, шрифт, рамки, заливка, параметри сторінки) тісно відображає об'єктну модель Excel, знайому з OLE Automation. Це робить міграцію наявних проектів на основі 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

Дивіться також