Класс TXLSXRange - Справочник разработчика HotXLS

Модуль: lxHandleX

Представляет прямоугольный диапазон листа XLSX, возвращаемый методами TXLSXWorksheet.Range, RCRange, UsedRange, EntireRow или EntireColumn. Диапазон является легковесным представлением поверх своего листа; он не владеет данными ячеек

Объявление

TXLSXBuiltinCellStyle = (
  xbsNormal, xbsGood, xbsBad, xbsNeutral,
  xbsCalculation, xbsCheckCell, xbsExplanatoryText, xbsInput,
  xbsLinkedCell, xbsNote, xbsOutput, xbsWarningText,
  xbsHeading1, xbsHeading2, xbsHeading3, xbsHeading4, xbsTitle, xbsTotal,
  xbsAccent1, xbsAccent2, xbsAccent3, xbsAccent4, xbsAccent5, xbsAccent6);

TXLSXRange = class
  constructor Create(ASheet: TXLSXWorksheet; ARow1, ACol1, ARow2, ACol2: Integer);
  function RefA1: WideString;
  function SaveAsHTML(const FileName: WideString): Integer; overload;
  function SaveAsHTML(const FileName: WideString; Options: TXLSXHtmlExportOptions): Integer; overload;
  function SaveAsHTML(Stream: TStream): Integer; overload;
  function SaveAsHTML(Stream: TStream; Options: TXLSXHtmlExportOptions): Integer; overload;

  property Sheet: TXLSXWorksheet;
  property Row1, Col1, Row2, Col2: Integer;
  property RowCount, ColCount: Integer;

  procedure SetValue(const V: Variant);
  procedure SetFormula(const F: WideString);
  function SetArrayFormula(const F: WideString): Integer;
  procedure ClearValues;
  procedure Clear;
  procedure ClearAll;

  procedure SetFontIndex(AIdx: Integer);
  procedure SetFillIndex(AIdx: Integer);
  procedure SetBorderIndex(AIdx: Integer);
  procedure SetNumberFormatIndex(AIdx: Integer);
  procedure SetAlignmentIndex(AIdx: Integer);
  procedure SetNumberFormat(const Fmt: WideString);
  procedure SetBorders(Kind: TXLSXBorderEdgeKind; Style: TXLSXBorderStyle); overload;
  procedure SetBorders(Kind: TXLSXBorderEdgeKind; Style: TXLSXBorderStyle; Color: LongWord); overload;
  procedure SetLocked(ALocked: Boolean);
  procedure SetFormulaHidden(AHidden: Boolean);

  procedure AutoFitColumns(AMinWidth: Double = 0; AMaxWidth: Double = 0);
  procedure AutoFitRows(AMinHeight: Double = 0; AMaxHeight: Double = 0);
  procedure Merge; overload;
  procedure Merge(Across: OleVariant); overload;
  procedure Unmerge;
  function Offset(DRow, DCol: Integer): TXLSXRange;
  function Resize(NewRowCount, NewColCount: Integer): TXLSXRange;
  procedure Sort(AKeyColumn: Integer; ADescending: Boolean = False); overload;
  procedure Sort(const AKeyColumns: array of Integer; const ADescending: array of Boolean); overload;
  procedure ApplyBuiltinStyle(AStyle: TXLSXBuiltinCellStyle);
  procedure CopyTo(ADestRow, ADestCol: Integer);
  procedure MoveTo(ADestRow, ADestCol: Integer);
  procedure InsertRows;
  procedure DeleteRows;
  procedure InsertCols;
  procedure DeleteCols;
  procedure ApplyFormatPatch(ASource: TXLSXRange; AParts: TXLSXFormatParts);
  function CopyToClipboard: Boolean;
  function SaveAsPDF(const FileName: WideString): Integer; overload;
  function SaveAsPDF(Stream: TStream): Integer; overload;
  function SetDynamicArrayFormula(const F: WideString): Integer;
end;

Элементы

Элемент	Описание
Create(ASheet, ARow1, ACol1, ARow2, ACol2)	Создает новый диапазон, принадлежащий листу, и нормализует перевернутые углы, так что `Row1`/`Col1` всегда представляют собой верхний левый угол
RefA1	Возвращает ссылку на диапазон в формате A1. Одноячеечные диапазоны возвращают ссылку на одну ячейку, например, `B2`
SaveAsHTML	Перегрузки с опциями принимают `TXLSXHtmlExportOptions` для настройки `Title`, `WriteDocument`, `IncludeStyles`, `IncludeBOM` и `TableClass`. Установите `WriteDocument` в значение `False` для получения фрагмента таблицы; установите `IncludeBOM` в значение `False` при встраивании вывода в существующий UTF-8 ответ. Те же опции доступны для экспорта в HTML выбранного диапазона. Экспортируемый вывод сохраняет гиперссылки ячеек в виде якорей `<a>`, а привязанные изображения — в виде встроенных URI изображений `data:`, если они попадают внутрь выбранного прямоугольника. Комментарии ячеек внутри выбранного прямоугольника также выводятся как экранированные атрибуты `title` тегов `<td>`. Если включено `IncludeStyles`, явные значения `ColWidth` выводятся как ширина `<col>`, а явные значения `RowHeight` — как стили высоты `<tr>`. Текстовые фрагменты ячеек с форматированием (rich-text) выводятся как экранированные элементы `<span>` со встроенными стилями шрифта, цвета, выделения и подчеркивания, если включено `IncludeStyles`. Границы ячеек выводятся в виде правил CSS `border-left`, `border-right`, `border-top` и `border-bottom`, если включено `IncludeStyles`. Скрытые строки и столбцы, отмеченные свойствами `RowHidden` / `ColHidden`, а также столбцы с явно заданной нулевой шириной, пропускаются в сгенерированной таблице и `<colgroup>`. Параметры вертикального выравнивания выводятся в виде правил CSS `vertical-align`, если включено `IncludeStyles`
SetValue / SetFormula	Записывает одно и то же значение или текст формулы в каждую ячейку диапазона через коллекцию ячеек листа
SetArrayFormula	Задает многоячеечную формулу массива CSE для диапазона. Верхняя левая ячейка хранит текст формулы и служит якорем для диапазона распределения, в то время как остальные ячейки указывают обратно на этот корень, чтобы каждая ячейка вычисляла свой собственный элемент результата матрицы. Передавайте текст формулы без окружающих фигурных скобок
ClearValues / Clear / ClearAll	Методы `ClearValues` и `Clear` удаляют значения и формулы, сохраняя индексы стилей. Метод `ClearAll` также очищает индексы стилей
SetFontIndex / SetFillIndex / SetBorderIndex / SetNumberFormatIndex / SetAlignmentIndex	Применяет индексы палитры книги (начиная с 1) к каждой ячейке диапазона. Передайте 0 для очистки соответствующего индекса конкретной ячейки
SetNumberFormat	Ищет или добавляет строку формата чисел в палитру книги, затем применяет полученный индекс (начиная с 1) к диапазону. Пустой формат очищает индекс конкретной ячейки
SetBorders	Создает границы по краям диапазона. `TXLSXBorderEdgeKind` принимает значения `xlsxEdgeAll`, `xlsxEdgeOutline`, `xlsxEdgeInside`, `xlsxEdgeInsideHorizontal`, `xlsxEdgeInsideVertical`, `xlsxEdgeTop`, `xlsxEdgeBottom`, `xlsxEdgeLeft`, `xlsxEdgeRight`, `xlsxEdgeDiagonalUp`, и `xlsxEdgeDiagonalDown`. Используйте селекторы внешних и внутренних границ для создания границ таблиц без замены не связанных с ними настроек краев
SetLocked / SetFormulaHidden	Применяет флаги защиты ячеек к каждой ячейке диапазона путем повторного использования пула стилей защиты книги
AutoFitColumns / AutoFitRows	Перенаправляет вызовы к помощникам автоподбора высоты/ширины листа в пределах столбцов или строк диапазона. Дополнительные ограничения ширины и высоты передаются для сохранения макетов отчетов в рамках проектных ограничений
Merge / Unmerge	Методы `Merge` и `Merge(False)` создают один объединенный прямоугольник. Метод `Merge(True)` создает по одному объединенному диапазону для каждой строки, что соответствует поведению объединения по строкам в Excel. Метод `Unmerge` удаляет точное совпадение объединенного диапазона
Offset / Resize	Возвращает другой диапазон, принадлежащий листу, смещенный относительно текущих границ или измененный до запрошенного количества строк и столбцов
Sort	Сортирует строки внутри этого диапазона по одному ключевому столбцу или по нескольким ключевым столбцам в порядке приоритета. Параметр `ADescending` выбирает порядок сортировки по возрастанию или убыванию для каждого ключа; опущенные записи по умолчанию сортируются по возрастанию. Пустые значения сортируются в последнюю очередь
ApplyBuiltinStyle	Применяет визуальный вид встроенного стиля ячейки Excel к каждой ячейке диапазона. Помощник записывает прямое форматирование, добавляя соответствующий шрифт и заливку в пулы книги и назначая полученные индексы ячейкам
CopyTo / MoveTo	Копирует или перемещает весь диапазон в указанную левую верхнюю ячейку назначения. Значения, формулы, форматированный текст, индексы стилей, комментарии, гиперссылки и якоря рисунков передаются через помощники копирования и перемещения диапазонов листа
InsertRows / DeleteRows / InsertCols / DeleteCols	Выполняет вставку и удаление целых строк или целых столбцов в пределах диапазона. Эти помощники перенаправляют вызовы операциям сдвига строк/столбцов листа, чтобы формулы, ссылки, фильтры, диапазоны параметров страницы, диапазоны диаграмм, имена, изображения и якоря диаграмм оставались выровненными с редактируемой сеткой
ApplyFormatPatch	Применяет выборочные стили форматирования из другого исходного диапазона к этому диапазону, используя флаги TXLSXFormatParts
CopyToClipboard	Копирует значения и стили диапазона в буфер обмена Windows
SaveAsPDF	Экспортирует диапазон ячеек в виде файла или потока PDF с использованием встроенного движка рендеринга PDF
SetDynamicArrayFormula	Задает динамическую формулу массива для диапазона, поддерживая динамическое распределение Excel

Владение и границы

Диапазоны принадлежат создавшему их листу и освобождаются вместе с ним. Код приложения не должен вызывать метод Free для TXLSXRange и не должен сохранять ссылку на диапазон после уничтожения листа или книги

Числовые координаты начинаются с 1. При создании диапазона нормализуются перевернутые углы и ограничиваются границы в соответствии с лимитами листа XLSX

Пример

var
  Wb: TXLSXWorkbook;
  Ws: TXLSXWorksheet;
  Body: TXLSXRange;
begin
  Wb := TXLSXWorkbook.Create;
  try
    Ws := Wb.Sheets.Add('Report');
    Body := Ws.Range['B2:D20'];
    Body.SetNumberFormat('#,##0.00');
    Body.SetBorders(xlsxEdgeOutline, xlsxBorderThin, $FF808080);
    Body.Sort(2);
    Body.ApplyBuiltinStyle(xbsAccent1);
    Ws.Range['F2:G3'].SetArrayFormula('MMULT(A2:B3,D2:E3)');
    Body.AutoFitColumns;
    Body.SaveAsHTML('report-fragment.html');
  finally
    Wb.Free;
  end;
end;

См. также

Класс TXLSXWorksheet
Класс TXLSXWorkbook
Обзор фасада XLSX