Дополнительные члены API фасада XLSX - Справочник разработчика HotXLS

Данная страница охватывает меньшие публичные члены API, объявленные в lxHandleX, включая параметры HTML-экспорта и вспомогательные функции для вызывающих сторон, работающих непосредственно со ссылками на ячейки XLSX или текстом XML

Параметры HTML-экспорта

property FormulaArrayMemoryLimit: Int64;

Ограничивает объём данных, выделяемый сгенерированными массивами формул, такими как MUNIT, по умолчанию 64 МиБ, применяется к параллельным воркерам пересчёта и ограничивает значения снизу одним Double element

HTML export options

type
  TXLSXHtmlExportOptions = class
    constructor Create;
    property Title: WideString;
    property WriteDocument: Boolean;
    property IncludeStyles: Boolean;
    property IncludeBOM: Boolean;
    property TableClass: WideString;
  end;

Title	Sets the document title when `WriteDocument` Задаёт заголовок документа, когда WriteDocument равно True
WriteDocument	Когда True, записывает полный HTML-документ. Когда False, записывает только фрагмент таблицы
IncludeStyles	Управляет тем, включает ли экспортируемый HTML сгенерированный CSS и встроенные сведения о стилях
IncludeBOM	Controls whether файл и stream output starts с UTF-8 BOM
TableClass	добавляет CSS класс имя к generated `<table>` element

Вспомогательные функции ссылок XLSX

function XlsxColumnLabel(Col: Integer): WideString;
function XlsxCellRef(Row, Col: Integer): WideString;
function XlsxColumnIndex(const ColumnLabel: WideString): Integer;
function XlsxParseCellRef(const Ref: WideString; out Row, Col: Integer): Boolean;
function XlsxParseRangeRef(const Ref: WideString; out Row1, Col1, Row2, Col2: Integer): Boolean;

XlsxColumnLabel	Converts 1-основанный столбец индекс к A1-стиль столбец label such as `A`, `Z`, или `AA`
XlsxCellRef	Builds A1-стиль ячейка справочник из 1-основанный строка и столбец номера
XlsxColumnIndex	Converts A1-стиль столбец label к 1-основанный столбец индекс
XlsxParseCellRef	Разбирает одиночную ссылку на ячейку в стиле A1 и возвращает координаты строки и столбца
XlsxParseRangeRef	Parses rectangular A1-стиль диапазон и возвращает inclusive 1-основанный bounds

Вспомогательные функции экранирования XML XLSX

function XlsxEscapeText(const Value: WideString): WideString;
function XlsxEscapeAttr(const Value: WideString): WideString;

XlsxEscapeText экранирует содержимое текстовых узлов XML, а XlsxEscapeAttr экранирует значения атрибутов XML и сохраняет пробелы атрибутов, которые Excel должен считать обратно точно

Пример

Продвинутые члены XLSX, описанные по всему этому файлу справки, принимают и возвращают следующие простые типы, объявленные в lxHandleX

{ Find and replace }
TXLSXFindFlag = (lxfMatchCase, lxfWholeCell, lxfSearchFormulas,
  lxfUseWildcards, lxfBackward, lxfByColumns);
TXLSXFindOptions = set of TXLSXFindFlag;
TXLSXReplaceAction = (raReplace, raSkip, raAbort);
TXLSXReplaceEvent = function(ARow, ACol: Integer;
  const ACurrentText: WideString; var ANewText: WideString):
  TXLSXReplaceAction of object;

{ Progress and recalculation policy }
TXLSXProgressPhase = (xlsxProgressReading, xlsxProgressWriting,
  xlsxProgressCalculating, xlsxProgressExporting);
TXLSXProgressState = (ppsBegin, ppsWork, ppsEnd);
TXLSXRecalcMode = (xrmManual, xrmIfDirty, xrmAlways);
TXLSXPasswordEvent = procedure(Sender: TObject;
  var PassWord: WideString) of object;

{ Custom document properties (docProps/custom.xml) }
TXLSXCustomPropType = (xcptText, xcptNumber, xcptDate, xcptBoolean);
TXLSXCustomProperty = class
  Name: WideString;
  PropType: TXLSXCustomPropType;
{ + TextValue, NumberValue, DateValue, BoolValue accessors }
end;

{ Table styles, fills, sorts, external links, controls, sparklines }
TXLSXTableStyleSectionKind = (xltssWholeTable, xltssHeaderRow,
  xltssTotalRow, xltssFirstColumn, xltssLastColumn, xltssFirstRowStripe,
  xltssSecondRowStripe, xltssFirstColumnStripe, xltssSecondColumnStripe,
  xltssFirstHeaderCell, xltssLastHeaderCell, xltssFirstTotalCell,
  xltssLastTotalCell { + subtotal and subheading slots });
TXLSXFillPattern = (xlsxFillNone, xlsxFillSolid, xlsxFillGray125
  { + the remaining ECMA-376 pattern values });
TXLSXGradientKind = (xlsxGradientNone, xlsxGradientLinear, xlsxGradientPath);
TXLSXSortBy = (xlsxBsValue, xlsxBsCellColor, xlsxBsFontColor, xlsxBsIcon);
TXLSXSortMethod = (xlsxSmNone, xlsxSmStroke, xlsxSmPinYin);
TXLSXExternalLinkKind = (xlsxExternalLinkUnknown, xlsxExternalLinkWorkbook,
  xlsxExternalLinkDde { + the remaining link kinds });
TXLSXFormControlType = (xfcButton, xfcCheckBox, xfcRadioButton, xfcComboBox,
  xfcListBox);
TXLSXSparklineAxisType = (xlsxSparklineAxisIndividual,
  xlsxSparklineAxisGroup, xlsxSparklineAxisCustom);
TXLSXSparklineEmptyCells = (xlsxSparklineEmptyGap, xlsxSparklineEmptyZero,
  xlsxSparklineEmptySpan);

{ Chart authoring and layout }
TXLSXChartBarGrouping = (xlsxBarGroupClustered, xlsxBarGroupStacked,
  xlsxBarGroupPercentStacked);
TXLSXChartMarkerSymbol = (xlsxMarkerAuto, xlsxMarkerCircle, xlsxMarkerDash,
  xlsxMarkerDiamond, xlsxMarkerDot, xlsxMarkerPlus, xlsxMarkerSquare,
  xlsxMarkerStar, xlsxMarkerTriangle, xlsxMarkerX, xlsxMarkerNone);
TXLSXChartDataLabelPos = (xlsxDlblPosDefault, xlsxDlblPosCenter,
  xlsxDlblPosInEnd, xlsxDlblPosOutEnd, xlsxDlblPosBestFit, xlsxDlblPosLeft,
  xlsxDlblPosRight, xlsxDlblPosTop, xlsxDlblPosBottom);
TXLSXChartMutable = class;     { mutable base of the chart model nodes }
TXLSXChartLayoutRect = record
  Left, Top, Right, Bottom: Double;
end;
TXLSXChartResolvedLayout = record
  ChartRect: TXLSXChartLayoutRect;
  TitleRect: TXLSXChartLayoutRect;
  LegendRect: TXLSXChartLayoutRect;
  PlotOuterRect: TXLSXChartLayoutRect;
  PlotInnerRect: TXLSXChartLayoutRect;
  { + per-axis title rectangles and visibility flags }
end;

{ Pagination keep-together blocks }
TXLSXKeepTogetherRange = record
  Row1, Row2: Integer;
  Level: Integer;
  ReplaceBiggerLevels: Boolean;
end;
TXLSXKeepTogetherCols = record
  Col1, Col2: Integer;
  Level: Integer;
  ReplaceBiggerLevels: Boolean;
end;

{ Diagnostics records }
TXLSXValidationIssue = record
  Row, Col: Integer;
  ValidationIndex: Integer;
  Reason: WideString;
end;
TXLSXUnknownFunctionInfo = record
  Sheet: Integer;
  Row, Col: Integer;
  Name: WideString;
  LocationKind: TXLSFormulaSymbolLocationKind;
  DefinedNameIndex: Integer;
  DefinedName: WideString;
end;
TXLSXRowMajorOrder = record
  CellOrder: array of Integer;
  RowStarts: array of Integer;
  MaxRow: Integer;
end;

Find and replace	`TXLSXWorksheet.FindText` / `FindTextIn` accept `TXLSXFindOptions` (учёт регистра, вся ячейка, поиск в формулах, подстановочные знаки, назад, по столбцам) и `ReplaceText` takes a `TXLSXReplaceEvent` whose result selects `raReplace`, `raSkip`, or `raAbort` per match, with a writable `ANewText` for per-cell substitutions
Progress and saving	`TXLSXWorkbook.OnProgress` / `OnProgressEx` deliver `TXLSXProgressPhase` and (extended form) `TXLSXProgressState` with an `Abort` flag; `RecalcBeforeSave` is a `TXLSXRecalcMode` который выбирает пересчёт — ручной, только изменённые или всегда — перед сериализацией; `OnPassword` is a `TXLSXPasswordEvent` that supplies open and write passwords
Custom properties	`TXLSXWorkbook.CustomProperties` is a `TXLSXCustomProperties` collection with typed `AddText` / `AddNumber` / `AddDate` / `AddBoolean` creators, `FindByName`, `Delete`, and `Clear`, plus `Count` and `Items` enumeration; each `TXLSXCustomProperty` tags its value with a `TXLSXCustomPropType` matching the ECMA-376 variant mapping
Style overlays	`TXLSXStyleOverlays` управляет наложениями по диапазонам поверх сохранённых стилей: `Add` creates one, `ApplyToCell` restyles a single cell, `Resolve`, `ResolveRowDefault`, and `ResolveColumnDefault` answer style lookups during load, `HasVirtualStyle` reports generated styles, `MaxVirtualRow` bounds virtual rows, `ApplyStructuralEdit` сдвигает наложения после правок строк или столбцов, а `Clear`, `Count`, and `Items` maintain the collection
Styles, fills, and overlays	`TXLSXFill` exposes `Pattern`, `GradientKind`, and `GradientStops` through `TXLSXFillPattern`, `TXLSXGradientKind`, and `TXLSXGradientStop`; `TXLSXWorksheet.StyleOverlays` is a `TXLSXStyleOverlays` collection whose `TXLSXStyleOverlay` записи несут прямоугольник, затронутые части формата и переопределяющий стиль ячейки
Tables, sorts, and links	Custom table styles (`TXLSXWorkbook.CustomTableStyles`) build section formatting from `TXLSXTableStyleSectionKind` slots: the collection offers `Add`, `FindByName`, `Delete`, `Clear`, `Count`, and `Items`, while each `TXLSXCustomTableStyle` exposes `Name`, `SectionSize`, `PivotStyle`, and `TableStyleFlag` and answers `HasSection` / `ResolveSection` поиск; условия сортировки классифицируют ключи через `TXLSXSortBy` and text ordering with `TXLSXSortMethod`; `TXLSXExternalLink.Kind` is a `TXLSXExternalLinkKind` and each link lists `TXLSXExternalDefinedName` entries with `Name` and `RefersTo`
Custom XML parts	`TXLSXWorkbook.CustomXmlParts` preserves item-specific custom XML: `Add`, `Delete`, and `Clear` maintain the parts, each `TXLSXCustomXmlPart` carries its payload in `Xml` plus an `ItemId` and a `SchemaRefs` string list of schema relationships (`AddSchemaRef` добавляет), а сохранённые части проходят цикл сохранения нетронутыми
Cell style payloads	`TXLSXCellStylePayload` — совместно используемый неизменяемый набор стилей, привязываемый к отдельным ячейкам: `Acquire` / `Release` manage its reference count, `Clone` copies it, `IsDefault` tests the default style, and `InternKey` идентифицирует равные данные, чтобы хранилище могло их дедуплицировать
Controls, drawings, and sparklines	`TXLSXWorksheet.FormControls` is a `TXLSXFormControls` collection of `TXLSXFormControl` objects — each exposes `ControlType`, `Caption`, `MacroName`, `LinkedCell`, and its `Items` list — typed by `TXLSXFormControlType`, with `TXLSXFormControlItems` с текстом элементов каждого элемента управления; объекты рисования сообщают свой вид через `TXLSDrawingObjectKind`, а группы спарклайнов раскрывают масштабирование оси и поведение пустых ячеек через `TXLSXSparklineAxisType` and `TXLSXSparklineEmptyCells`
Charts	Группы построения и ряды классифицируют группировку гистограмм, символы маркеров и позиции подписей данных через `TXLSXChartBarGrouping`, `TXLSXChartMarkerSymbol`, and `TXLSXChartDataLabelPos` enums; the chart model nodes share the `TXLSXChartMutable` base class, and `TXLSXChartLayoutResolver.ResolveChart` fills a `TXLSXChartResolvedLayout` of `TXLSXChartLayoutRect` прямоугольники для диаграммы, заголовка, легенды, области построения и заголовков осей
Pagination keep blocks	`KeepRowsTogether` / `KeepColumnsTogether` on the XLSX pagination surface maintain `TXLSXKeepTogetherRange` and `TXLSXKeepTogetherCols` записи, чтобы планирование разрывов страниц удерживало блок на одной странице
Diagnostics	`TXLSXWorksheet.CheckDataValidations` returns `TXLSXValidationIssue` записи (ячейка, индекс проверки, причина); `TXLSXWorkbook.ScanUnknownFunctions` returns `TXLSXUnknownFunctionInfo` записи, локализующие нереализованные вызовы в ячейках и определённых именах; `TXLSXCells.GetStorageStatistics` fills a `TXLSXCellStorageStatistics` запись с учётом ячеек, блоков строк, байтов на данные и оформленных пустых ячеек; `TXLSXWorksheet.BuildRowMajorCellOrder` returns a `TXLSXRowMajorOrder` описывающий порядок обхода заполненных ячеек в памяти

TXLSXWorkbook.FormulaLocale читает или пишет тег локали, используемый при разборе и сериализации формул, зеркаля обработку локали формул классической книги

Table slicers

Слайсеры таблиц (Excel 2013+) записываются и осматриваются через две коллекции: TXLSXWorksheet.Slicers holds the per-sheet slicer views (TXLSXSlicer) and TXLSXWorkbook.SlicerCaches holds the shared data sources (TXLSXSlicerCache)

property TXLSXWorksheet.Slicers: TXLSXSlicers;
property TXLSXWorkbook.SlicerCaches: TXLSXSlicerCaches;

{ TXLSXSlicers }
function Add(ATable: TXLSXTable; const AColumnName: WideString): TXLSXSlicer; overload;
function Add(ATable: TXLSXTable; const AColumnName: WideString;
  ARow1, ACol1, ARow2, ACol2: Integer): TXLSXSlicer; overload;
function IndexByName(const AName: WideString): Integer;
function FindByName(const AName: WideString): TXLSXSlicer;
procedure Delete(Index: Integer);
procedure Clear;
property Count: Integer;
property Items[Index: Integer]: TXLSXSlicer;

{ TXLSXSlicer view }
property Name: WideString;          { workbook-unique }
property CacheName: WideString;
property Cache: TXLSXSlicerCache;
property Caption: WideString;
property StartItem: Integer;
property ColumnCount: Integer;
property ColumnWidth: WideString;
property ShowCaption: Integer;
property StyleName: WideString;
property LockedPosition: Integer;
property RowHeight: WideString;
property RowHeightEmu: Integer;
procedure SetBounds(ARow1, ACol1, ARow2, ACol2: Integer);
property FromRow, FromCol, ToRow, ToCol: Integer;   { anchor cell corners }
property FromRowOff, FromColOff, ToRowOff, ToColOff: Integer; { EMU offsets }
property AnchorType: TXLSXAnchorEditAs;
property HasAnchor: Boolean;

{ TXLSXSlicers, load-path entry }
function AddInternal: TXLSXSlicer;

{ TXLSXSlicerCache }
property Name: WideString;          { e.g. Slicer_Region }
property SourceName: WideString;    { source table column / pivot field }
property IsTableCache: Boolean;
property IsPivot: Boolean;
property IsNonOlapPivot: Boolean;
property ItemCount: Integer;
property ItemCacheIndex[Index: Integer]: Integer;
property ItemSelected[Index: Integer]: Boolean;
function SetSelectedItems(const CacheItemIndices: array of Integer): Integer;
function ClearSelection: Integer;
property TableId: Integer;
property TableColumnId: Integer;
property SortOrder: WideString;     { '' | ascending | descending }
property CrossFilter: WideString;   { '' | none | showItemsWithDataAtTop | showItemsWithNoData }
property CustomListSort: Integer;   { -1 absent, else 0/1 }

{ TXLSXSlicerCaches }
function Add: TXLSXSlicerCache;
function FindByName(const AName: WideString): TXLSXSlicerCache;
function IndexOfName(const AName: WideString): Integer;
function FindForTableColumn(ATableId, ATableColumnId: Integer): TXLSXSlicerCache;
procedure Delete(Index: Integer);
procedure Clear;
property Count: Integer;
property Items[Index: Integer]: TXLSXSlicerCache;

Slicers.Add(Table, ColumnName) строит слайсер от начала до конца: он регистрирует или переиспользует поддерживающий кэш с именем Slicer_<column>, reserves the matching #N/A defined name, writes the worksheet slicerList расширение и привязывает представление якорем рисования markup-compatibility, чьё запасное уведомление покрывает старые версии Excel; вторая перегрузка фиксирует прямоугольник представления, иначе используется якорь по умолчанию справа от таблицы

Загруженные представления и кэши разбираются обратно при открытии, общие кэши переиспользуются между представлениями, а удаление последнего представления кэша удаляет сам кэш; нераспознанные атрибуты и расширения сохраняют исходное представление, при этом табличные привязки отслеживают сохранённые id таблиц, а поддерживаемые подключения Pivot отслеживают сохранённые идентичности листов

Поддерживаемые импортированные не-OLAP кэши сводных таблиц открывают типизированный осмотр членов и защищённые изменения выбора через IsNonOlapPivot, ItemCount, ItemCacheIndex, ItemSelected, SetSelectedItems и ClearSelection; поведение общих представлений, атомарность сбоев и границу маски одноимённых полей импорта см. в разделе выбора Pivot Slicer

Неподдерживаемые кэши сводных таблиц сохраняют свои исходные байты; представление слайсера, загруженное из файла, также доступно как объект рисования через TXLSXDrawingObject.Slicer

Example

var
  Ref: WideString;
  Row, Col: Integer;
begin
  Ref := XlsxCellRef(10, 5);
  if XlsxParseCellRef(Ref, Row, Col) then
    Worksheet.Cells.Item[Row, Col].Value := 'Checked';
end;

Обратные вызовы ввода-вывода, пулы стилей сериализатора, проверку зашифрованных файлов и контракты графа зависимостей рабочей области см. в разделе API инфраструктуры книги