Дополнительные члены API библиотеки

Эта страница дополняет справочник по открытым типам, которые поддерживают основные API книги, листа, отрисовки, импорта, диагностики и средства просмотра, но не требуют отдельного тематического руководства

Фильтрация и условное форматирование

TXLSCfValue, TXLSDataBarSpec, TXLSColorScaleSpec, TXLSIconSetSpecи TXLSDxfStyle принимают AttachWriteGuardOwner, связывающий объект правила с владеющей книгой, чтобы изменения автоматически получали защиту записи; владелец реализует TXLSCondFormatWriteGuardOwner, чей единственный метод AcquireWriteGuard передаёт правилу защиту записи книги. TXLSDxfStyle добавляет FontColorIndex с FontColorIsIndexed , а также пары FillFgColorIndex / FillFgColorIsIndexed и FillBgColorIndex / FillBgColorIsIndexed для цветов правил в виде индексов палитры, плюс именованные переопределения дифференциального шрифта — FontName, FontSizeи FontScheme (пустая строка, размер в пунктах или слот шрифта темы вроде major / minor) — рядом с уже существующими членами полужирного, курсива, подчёркивания и цвета; каждое присваивание получает защиту записи и помечает правило «грязным» для повторной эмиссии

TXLSConnections, TXLSDataTablesи TXLSQueryTables открывают OnAcquireWriteGuard (типы TXLSConnectionAcquireWriteGuard, TXLSDataTableAcquireWriteGuardи TXLSQueryTableAcquireWriteGuard) — перехватчик, который их пути изменения используют, чтобы получить IXLSWorkbookWriteGuard владеющей книги перед изменением и увеличить поколение книги после него; защита записывает StartGeneration, а Complete отмечает запись завершённой, чтобы зависимые кэши могли перестроиться

Сохранённые подключения данных несут типизированное описание: TXLSConnectionKind (xlckUnknown, xlckOdbc, xlckDao, xlckFile, xlckWeb, xlckOleDb, xlckText, xlckAdo) классифицирует подключение, TXLSConnectionCredentials (xlccIntegrated, xlccNone, xlccStored, xlccPrompt) фиксирует его режим аутентификации, а каждое значение параметра подключения помечено видом TXLSConnectionParameterValueKind (xlcpvNone, xlcpvBoolean, xlcpvDouble, xlcpvInteger, xlcpvString, xlcpvCell). Таблицы данных «что если» сообщают вид своего сохранённого определения через TXLSDataTableKind

Таблицы данных «что если» и группировка сводных таблиц

Пороги наборов значков можно отрисовать или проверить программно: XLSCfIconSetCount сообщает, сколько значков определяет TXLSIconSetType , а XLSBuildCfIconGeometry заполняет TXLSCfIconGeometry примитивами (TXLSCfIconPrimitiveс видом TXLSCfIconPrimitiveKind: cfipPolygon, cfipEllipse, cfipRect, cfipLine) и точками (TXLSCfIconPoint), которыми рисуется один значок, чтобы собственные отрисовщики совпадали со встроенными фигурами значков Excel

Диагностика, трассировка формул и валидация

Схемы валидации импорта

TXLSImportCheck из lxImportCheck проверяет TXLSXWorksheet по правилам, принадлежащим приложению; он осматривает сохранённые скалярные значения и сохранённые результаты формул, с координатами листа с отсчётом от единицы и без неявного преобразования текста в число, текста в дату или текста в Boolean

Validator := TXLSImportCheck.Create;
try
  Validator.HeaderRow := 1;
  Rule := Validator.AddRule(2);
  Rule.Name := 'quantity';
  Rule.Flags := [irRequired, irValueType, irValueRange];
  Rule.ValueKind := ivkInteger;
  Rule.MinimumValue := 1;
  Rule.MaximumValue := 1000;

  Validator.AddUniqueRule([1, 3]).Name := 'account-and-region';
  Validator.AddCrossColumnRule(4, 5, icLessOrEqual).Name := 'start-before-end';
  FailureCount := Validator.Check(Sheet);
  if FailureCount > 0 then
    Validator.Annotate(Sheet, 'Import validator');
finally
  Validator.Free;
end;

HeaderRow > 0 начинает проверку со следующей строки и имеет приоритет над FirstRow; иначе FirstRow по умолчанию равен 1; LastRow = 0 использует последнюю использованную строку листа, а положительный LastRow может включать отсутствующие ячейки, не создавая их; столбцы должны быть в пределах от 1 до 16,384, а активные границы строк данных — от 1 до 1,048,576

Правила столбцов и явные типы

AddRule(Column) заменяет и освобождает любое предыдущее правило этого столбца; предикаты типа значения, диапазона, длины и шаблона пропускают отсутствующие значения, null и пустые строки, тогда как irRequired сообщает о них; уникальность сохраняет описанные ниже различные политики; непустой пробельный текст остаётся значением; число не считается Boolean, дата не считается обычным числом, а похожая на число строка остаётся текстом

Присвоение MinimumValue или MaximumValue включает эту границу; любой из переключателей HasMinimum или HasMaximum может снова её отключить; оба переключателя инклюзивности по умолчанию True; границы должны быть конечными типизированными числами или датами, а две границы должны быть сравнимы и описывать непустой интервал; перевёрнутые, отсутствующие, несовместимые или пустые границы возбуждают исключение до начала валидации листа

Числовые границы сравнивают числовые значения, а границы дат сравнивают даты; сравнения целое-с-целым сохраняют все биты Int64 и UInt64; значения несовместимой категории не проходят проверку диапазона; предикаты длины текста и регулярных выражений продолжают осматривать текстовое представление скаляра, а проверки regex сохраняют существующее поведение IsMatch, поэтому используйте якоря вроде ^...$, когда должен совпасть весь текст; недопустимое регулярное выражение ради совместимости отключает свою проверку шаблона

Отформатированные как даты значения Excel

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

Rule := Validator.AddRule(4);
Rule.Flags := [irRequired, irValueType, irValueRange];
Rule.ValueKind := ivkDate;
if Sheet.Workbook.Date1904 then
  Rule.DateSerialMode := idsExcel1904
else
  Rule.DateSerialMode := idsExcel1900;
Rule.MinimumValue := VarFromDateTime(EncodeDate(2026, 1, 1));
Rule.MaximumValue := VarFromDateTime(EncodeDate(2026, 12, 31));

VarFromDateTime объявлен в Variants, а EncodeDate — в SysUtils; числовые порядковые номера должны быть неотрицательными и разрешаться до 1 января 10000 года; дробные порядковые номера сохраняют своё время суток; система 1900 отклоняет каждый номер от 60 включительно до 61 исключительно, потому что этот интервал обозначает фиктивный високосный день; система 1904 отображает нулевой номер в 1 января 1904 года

Границы дат включают время суток, поэтому максимум, установленный на полночь 31 декабря, исключает более позднее время этого дня; используйте исключающую верхнюю границу 1 января следующего года, когда должен приниматься весь последний день; текстовые даты вроде 10/08/2026 остаются текстом независимо от настроенного режима порядковых номеров

Составная уникальность и межстолбцовые сравнения

Составные ключи сохраняют точный тип Variant и текстовую идентичность каждого члена; Integer(1), Double(1), строка '1', Boolean и дата — различные члены; нет складывания регистра, нормализации Unicode, разбора по локали или неоднозначности разделителей; комбинации вроде ('ab', 'c') и ('a', 'bc') остаются различными; каждый проход валидации начинает свежий индекс кортежей

Когда SkipIncompleteRows = True, отсутствующий, null или пустой строковый член исключает строку из уникальности кортежей; установка в False включает такие члены с их исходными идентичностями Variant; дубликат сообщает первый столбец кортежа как адрес ячейки и первую совпавшую строку через FirstDuplicateRow

Существующий одноколончатый irUnique сохраняет своё текстовое сопоставление без учёта регистра и пропускает отсутствующие или null значения; используйте AddUniqueRule([Column]), когда для одного столбца нужна строгая типизированная идентичность

Межстолбцовые сравнения никогда не приводят строки к числам, числа к Boolean или обычные числа к датам; смешанные несовместимые категории не проходят даже для icNotEqual; строковые сравнения различают составленную и разложенную формы Unicode, сохраняют встроенные нулевые символы и используют порядок «сначала более короткий префикс»; когда SkipBlankValues = False, любой пустой операнд даёт межстолбцовое нарушение

Структурированные результаты и книги-исправления

Check(Sheet) возвращает количество нарушений, а ViolationCount вместе с базирующимся на нуле Violation(Index) перечисляют отчёт; одно правило столбца сообщает свой первый не прошедший предикат, тогда как независимо настроенные правила кортежей и сравнений могут добавить дальнейшие нарушения для той же ячейки; присваивайте осмысленные значения Name, когда вызывающему коду нужны стабильные идентификаторы правил приложения

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

OnVerifyCell сохраняет сигнатуру callback TlxImportVerifyCell и выполняется после успешных применимых предикатов столбца и проверок уникальности; он возвращает Boolean и может задать сообщение об ошибке приложения; callback не должны менять книгу или схему валидации, а записи в книгу отклоняются арендой чтения; исключения callback распространяются, и аренда освобождается для последующих операций

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

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

Политики сохранения внешних ссылок

TXLSExternalLinkUpdateMode = (xluPromptUser, xluNever, xluAlways);

property IXLSWorkbook.SaveExternalLinkValues: Boolean;
property IXLSWorkbook.UpdateLinks: TXLSExternalLinkUpdateMode;
property TXLSXWorkbook.SaveExternalLinkValues: Boolean;
property TXLSXWorkbook.UpdateLinks: TXLSExternalLinkUpdateMode;
      

Аудит вычислений и подсказки книги

function TXLSWorkbook.RecalcAndVerify(MaxIssues: Integer = 10000): TXLSCalculationAuditReport;
function TXLSXWorkbook.RecalcAndVerify(MaxIssues: Integer = 10000): TXLSCalculationAuditReport;
function TXLSWorkbook.RecalcAndVerifyEx(const Options: TXLSRecalcAuditOptions): TXLSCalculationAuditReport;
function TXLSXWorkbook.RecalcAndVerifyEx(const Options: TXLSRecalcAuditOptions): TXLSCalculationAuditReport;
function TXLSWorkbook.RunCalculationAudit(const Options: TXLSRecalcAuditOptions): TXLSCalculationAuditReport;
function TXLSWorkbook.FormulaIsVolatile(Formula: WideString): Boolean;

function TXLSWorkbook.AuditOverlayHash(SheetIndex, Row, Col: Integer): Integer;
function TXLSWorkbook.AuditOverlayRead(SheetIndex, Row, Col: Integer; var Value: Variant): Boolean;
procedure TXLSWorkbook.AuditOverlayWrite(SheetIndex, Row, Col: Integer; const Value: Variant);
procedure TXLSWorkbook.AuditOverlayClear;

TXLSCalculationAuditIssueKind = (xlcaiCacheMismatch, xlcaiParseFailure,
  xlcaiMissingFunction, xlcaiMissingName, xlcaiUnsupportedArguments,
  xlcaiCircularReference, xlcaiExternalReferenceDenied,
  xlcaiExternalReferenceMissing, xlcaiDataTableSkipped, xlcaiCancelled,
  xlcaiInternalFailure);

TXLSCalculationAuditIssue = record
  Kind: TXLSCalculationAuditIssueKind;
  SheetIndex: Integer;
  SheetName: WideString;
  Row: Integer;
  Col: Integer;
  Formula: WideString;
  Symbol: WideString;
  Expected: Variant;
  Actual: Variant;
  ResultCode: Integer;
  Stack: WideString;
  ExternalTarget: WideString;
end;
TXLSCalculationAuditIssues = array of TXLSCalculationAuditIssue;

TXLSRecalcAuditProgress = procedure(ASender: TObject;
  ACurrent, ATotal: Integer; var ACancel: Boolean) of object;

property WorkbookCodeName: WideString;
property CalculationThreadMode: TXLSCalculationThreadMode;
property ForceFullCalculationState: TXLSOptionalBooleanState;
property RefreshAllOnLoadState: TXLSOptionalBooleanState;
      

Состояние формул таблиц и IME

property TXLSXTable.ColumnCalculatedFormulaArrayStates[Index: Integer]: TXLSTableFormulaArrayState;
property TXLSXTable.ColumnTotalsFormulaArrayStates[Index: Integer]: TXLSTableFormulaArrayState;
property TDataValidation.ImeMode: TXLSDataValidationImeMode;
property TXLSXDataValidation.ImeModeKind: TXLSDataValidationImeMode;
      

Проверка и удаление областей задач веб-надстроек

function IXLSWorkbook.HasWebAddinTaskPanes: Boolean;
function IXLSWorkbook.WebAddinTaskPaneCount: Integer;
function IXLSWorkbook.RemoveWebAddinTaskPanes: Integer;
function TXLSXWorkbook.HasWebAddinTaskPanes: Boolean;
function TXLSXWorkbook.WebAddinTaskPaneCount: Integer;
function TXLSXWorkbook.RemoveWebAddinTaskPanes: Integer;
      

Политика отображения объектов книги

TXLSObjectDisplayMode = (xlsodmShowAll, xlsodmShowPlaceholders,
  xlsodmHideAll);

property IXLSWorkbook.ObjectDisplayMode: TXLSObjectDisplayMode;
property TXLSWorkbook.ObjectDisplayMode: TXLSObjectDisplayMode;
property TXLSXWorkbook.ObjectDisplayMode: TXLSObjectDisplayMode;
property TXLSPaginationModel.ExportObjectPlaceholders: Boolean;
property TXLSPDFExport.ExportObjectPlaceholders: Boolean;
property TXLSSvgExport.ExportObjectPlaceholders: Boolean;
property TXLSPageImageExporter.ExportObjectPlaceholders: Boolean;
property TXLSPrintDocument.ExportObjectPlaceholders: Boolean;
property TXLSXHtmlExportOptions.ExportObjectPlaceholders: Boolean;
      

Значения калибровки отрисовки и снимки

TXLSRenderCalibration = record
  WidthCorrection: Double;
  HeightCorrection: Double;
  LineSpacing: Double;
  CellMarginFactor: Double;
  ScreenScaling: Integer;
  MeasurementDpi: Integer;
end;

function XLSDefaultRenderCalibration: TXLSRenderCalibration;
function XLSValidateRenderCalibration(const AValue: TXLSRenderCalibration;
  out AInvalidField: TXLSRenderCalibrationField): Boolean;
      

Геометрия отрисовки и измерение шрифтов

TXLSRenderGeometryBackend = (xlsrgbAutoFit, xlsrgbPagination, xlsrgbPdf,
  xlsrgbSvg, xlsrgbBitmap, xlsrgbPrintPreview, xlsrgbViewer, xlsrgbHtml);

TXLSRenderFont = record
  Name: WideString;
  Size: Double;
  Styles: TXLSRenderFontStyles;
  Charset: Byte;
end;

function CreateXLSRenderGeometry(
  const ACalibration: TXLSRenderCalibration;
  AWorkbookGeneration: UInt64;
  ABackend: TXLSRenderGeometryBackend;
  ACacheCapacity: Integer = 4096): IXLSRenderGeometry;

property TXLSHTMLExport.RenderGeometry: IXLSRenderGeometry;
property TXLSXHtmlExportSession.RenderGeometry: IXLSRenderGeometry;
      

Импорт, генерация кода, сравнение и мониторинг

Сравнение книг

TXLSXWorkbookCompare в lxCompare сравнивает два экземпляра TXLSXWorkbook, не пересчитывая формулы и не изменяя ни одну из книг; листы сопоставляются по имени без учёта регистра, и одно лишь изменение порядка листов не создаёт различия

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

Сравнение литералов различает числа, текст, Boolean-значения, даты, ошибки и пустые значения: число 1 отличается от текста '1', Boolean отличается от своего текстового написания, даты сохраняют собственный тип, а ошибки сравниваются по сохранённому коду ошибки; числовые типы хранения с равными значениями сравниваются как равные, при этом различные значения Int64 остаются различными при точном сравнении

Options имеет тип TlxCompareOptions — набор TlxCompareOption; включение опции добавляет её различия к сравнению по умолчанию

SetFeatureLimits(MaxBytes, MaxItems) проверяет оба положительных лимита до изменения любой настройки; MaxFeatureBytes по умолчанию равен 64 МиБ, MaxFeatureItems — 1,000,000, а отдельные сеттеры сохраняют ту же атомарную валидацию

Бюджеты функций покрывают агрегированные отсоединённые канонические байты и сосчитанные записи из обеих книг, включая прогоны rich text, узлы XML фильтров, поля Pivot, членов доменов и значения записей, а также подключения slicer или шкал времени; читатели проверяют количества и большие текстовые входы до построения нативного XML, обеспечивают ограниченные выходные потоки и возбуждают EXLSXSemanticBudget при превышении лимита

SetNumericTolerance(AbsoluteTolerance, RelativeTolerance) проверяет оба аргумента до изменения любой настройки; оба должны быть конечными и неотрицательными, а отдельные сеттеры AbsoluteTolerance и RelativeTolerance используют ту же валидацию

Числовые литералы и числовые значения кэшей сравниваются как равные, когда их абсолютная разность не превышает AbsoluteTolerance или их разность относительно большего абсолютного значения не превышает RelativeTolerance; порог ноль сохраняет точное равенство, относительное вычисление избегает переполнения для крайних противоположных значений, а допуск не приводит текст и не применяется к датам, стилям или геометрии

LeftName и RightName задают необязательные отображаемые имена, используемые строками Report, по умолчанию left и right; имена влияют только на отчётность, а не на сопоставление листов или сравнение

Comparer := TXLSXWorkbookCompare.Create;
try
  Comparer.Options := [lcoFormulaCachedResults, lcoCellStyles,
    lcoAxisGeometry];
  Comparer.SetNumericTolerance(0.001, 0.000001);
  DifferenceCount := Comparer.Compare(LeftWorkbook, RightWorkbook);
  for I := 0 to DifferenceCount - 1 do
  begin
    Entry := Comparer.Diff(I);
    ReportLines.Add(Entry.Describe);
  end;
finally
  Comparer.Free;
end;

Compare возвращает количество различий, Count читает это количество после, а Diff(Index) использует индексацию с нуля и возвращает принадлежащий сравнителю TlxCompareDiff; удерживайте сравнитель при чтении его записей и заново получите записи после другого успешного сравнения

Каждая запись предоставляет Kind, Sheet, однобазовые Row и Col, где применимо, Ref, LeftText, RightText и типизированные значения LeftKind / RightKind; TlxCompareValueKind содержит lcvNone, lcvBlank, lcvNumber, lcvText, lcvBoolean, lcvDateTime, lcvErrorи lcvFormula, причём lcvNone используется для отсутствующей стороны или различия, не являющегося значением

TlxCompareKind сохраняет lckSheetAdded, lckSheetRemoved, lckCellAdded, lckCellRemoved, lckValueChanged, lckFormulaChanged, lckMergeAddedи lckMergeRemoved, а также добавляет lckFormulaCacheChanged, lckStyleChanged, lckRowGeometryChangedи lckColumnGeometryChanged

Различия стилей несут стабильные канонические отпечатки стилей в LeftText и RightText; различия геометрии несут сравниваемые размер, скрытие, структуру и свёрнутость, причём Ref идентифицирует затронутый непрерывный интервал оси, Row установлен на его первую строку и Col в ноль для строк, либо Col установлен на его первый столбец и Row в ноль для столбцов

Различия функций используют lckDefinedNameChanged, lckDataValidationChanged, lckConditionalFormatChanged, lckTableChanged, lckDrawingChanged, lckPivotTableChanged, lckPivotCacheChanged, lckSlicerChangedили lckTimelineChanged; Change — это lccChanged, lccAddedили lccRemoved, и каждая присутствующая сторона несёт канонический отпечаток своего определения, тогда как отсутствующая сторона несёт пустую строку

lckRichTextChanged идентифицирует изменённое определение прогона по координате его ячейки и несёт канонические отпечатки прогонов в LeftText и RightText; числовой допуск применяется к литералам ячеек и кэшам формул, тогда как типизированные определения функций сравниваются точно

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

lckBlankStyleRegionChanged идентифицирует изменённый пустой прямоугольник через Row, Col, инклюзивные LastRowи LastCol и его A1 Ref; сохранённые координаты обрабатываются обычным сравнением ячеек и lcoCellStyles, поэтому включите обе опции стилей, чтобы осматривать сохранённые ячейки и пустые области вместе

Describe форматирует одну запись, а Report(List) добавляет отформатированные записи в принадлежащий вызывающему коду TStrings; изменение типизированного значения включает метки типов, когда типы различаются, а результаты сортируются по имени листа, строке, столбцу, виду различия и ссылке, а не по порядку вставки ячеек

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

Неудавшееся сравнение сохраняет предыдущий успешный результат; недопустимое присвоение допуска также сохраняет существующие настройки и результат, а передача nil-книги очищает результат и возвращает ноль

Это сравнение покрывает сохранённое содержимое ячеек фасада XLSX и выбранные типизированные определения функций; написание формул имён, проверок, условного форматирования, таблиц и диаграмм нормализуется через семантический парсер формул, тогда как вычисляемые формулы Pivot сохраняют свой сохранённый текст определения

Фильтры таблиц принимают поддерживаемые формы custom, списка значений, группы дат, цвета, значка, динамические и top-count, а также условия сортировки; независимые столбцы фильтров и записи наборов значений нормализуют свой порядок, значения Boolean по умолчанию и числовые написания нормализуются, а порядок условий сортировки остаётся значимым

Сравнение типизированных Pivot, slicer и шкал времени разрешает поддерживаемые локальные источники листов и не-OLAP привязки без обновления или оценки доступности; нативные подсказки доступности slicer — производные отображаемые метаданные, тогда как выборы членов и распознанные нативные метаданные сортировки сравниваются

Непрозрачные нативные свойства рисования, неполные бинарные модели Pivot, внешние или OLAP источники Pivot, сырые дополнительные записи сводных таблиц и XML расширений, неизвестный XML фильтров, а также немоделированные атрибуты или дочерние элементы расширений slicer или шкал времени возбуждают EXLSSemanticSnapshot; сохранение таких данных не подразумевает семантической эквивалентности

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

TSimpleDomNode.RawName открывает исходный QName элемента рядом с нормализованным читателем Name, позволяя чувствительный к пространствам имён осмотр без изменения существующего сопоставления имён парсера

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

Эффективные свойства rich text

TMsoFbtOpt.StoredPids возвращает сохранённые идентификаторы свойств OfficeArt в отсортированном порядке, а TMsoFbtSp.PersistentFlags открывает нативные флаги фигур без выделения свойств или якорей

TMsoShapeContainer.HasPreservedObjectData идентифицирует удерживаемые хвостовые байты OBJ; HasOrdinaryEmbeddedPictureObjectData проверяет, что хвосты изображений содержат только распознанные записи формата буфера обмена и нулевые флаги изображения, и отклоняет связанные или неизвестные записи без копирования полезной нагрузки

TMSOShapeTextBox.HasValidTextRuns проверяет сохранённые границы прогонов TXO и зарезервированные поля без создания прогонов; TMsoDrawing.HasUnmodeledAppearance идентифицирует нативные данные рисования, пропущенные типизированным парсером, позволяя захвату явно отклонять неразрешённый внешний вид

TXLSXRichTextRun.BoldSet, ItalicSet, StrikethroughSet, UnderlineSet, VertAlignSetи ColorSet отличают унаследованные свойства шрифта от явных переопределений, включая ложные флаги, none, baseline и автоматические цвета; сеттеры помечают свойство явным, даже когда его значение равно начальному значению по умолчанию нового прогона

TXLSXRichText.HasUnsupportedAppearance сообщает о нативных rich-свойствах, которые типизированная модель прогонов не может представить; переносимый захват и эффективное сравнение rich text явно отклоняют такие прогоны, тогда как поддерживаемые свойства общих/встроенных прогонов и пробельные символы сохраняют импортированную семантику

Эффективное сравнение rich text применяет явные переопределения false до объединения соседних одинаковых прогонов; унаследованные и явно очищенные свойства остаются различными при дедупликации shared strings и поддерживаемых круговых преобразованиях XML

TXMLReader.ResolveNamespaceUri(Prefix, Uri) разрешает текущую действующую привязку пространства имён, не меняя позицию читателя, и возвращает false, когда привязки нет; пустой префикс запрашивает пространство имён по умолчанию, а сырые QName остаются доступны для чувствительного к пространствам имён осмотра

Неизменяемые записи rich/сцены, расширение источника захвата и контракт передачи HXRSNP02 описаны на странице Portable headless output

Отсоединённый осмотр стилей и осей

TXLSXWorksheet.ReadSemanticCellStyle(Row, Col) возвращает отсоединённый TXLSSemanticCellStyle для допустимых координат с отсчётом от единицы, разрешая сохранённые и упакованные стили, значения листа по умолчанию, применимые наложения стилей, неявные форматы дат, индексированные цвета и цвета тем без материализации ячеек или изменения пулов стилей; публичный вызов получает аренду чтения и исключает правила условного форматирования и стилей таблиц

TXLSXWorksheet.GetStoredAxisSpans(IsRow) возвращает TXLSXAxisSpans — массив записей TXLSXAxisSpan с инклюзивными FirstIndexи LastIndex с отсчётом от единицы; он сообщает следы метаданных размера, скрытия, структуры и свёрнутости, сохраняет компактные интервалы высот повторяющихся строк и оставляет эффективное значение листа по умолчанию доступным через его обычные свойства

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

TXLSXWorksheet.GetStoredStyleRegions возвращает отсоединённые TXLSXStyleRegions, содержащие инклюзивные границы FirstRow, FirstCol, LastRowи LastCol для компактных следов виртуального форматирования; эти следы могут перекрываться, а вызывающий код читает их эффективный внешний вид через ReadSemanticCellStyle

TXLSXWorkbook.ReadSemanticFeatures(Kind, Sheet, MaxBytes, MaxItems) возвращает отсоединённые записи TXLSXSemanticFeatures со стабильным Key, каноническими байтами Definitionи сосчитанным ItemCount; необязательные положительные лимиты по умолчанию равны 64 МиБ и 1,000,000 записей

TXLSXSemanticFeatureKind содержит xlsxSemanticDefinedNames, xlsxSemanticDataValidations, xlsxSemanticConditionalFormats, xlsxSemanticTables, xlsxSemanticDrawings, xlsxSemanticPivotTables, xlsxSemanticPivotCaches, xlsxSemanticSlicers, xlsxSemanticSlicerCaches, xlsxSemanticTimelinesи xlsxSemanticTimelineCaches

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

TXLSXWorksheet.ReadSemanticRichText(Row, Col, IncludePlainText, MaxBytes, MaxItems, ConsumedItems) возвращает отсоединённые канонические байты прогонов для координат с отсчётом от единицы или пустой буфер, когда rich text нет и IncludePlainText ложно; необязательный ConsumedItems: PInteger получает количество захваченных прогонов, а захват обычного текста сохраняет упакованное хранилище

TXLSPivotCacheField.GroupItemTypes[Index] открывает типизированный вид, соответствующий GroupItemLabels[Index], и отклоняет индекс вне сохранённого домена сгруппированных подписей

Метаданные формул и callback запросов Pivot

TXLSGetCellFormulaText и TXLSCalculator.OnGetCellFormulaText читают сохранённый текст выражений с однобазовым SheetIndex и базирующимися на нуле Row/Col, возвращая lxOk или типизированный код ошибки и соблюдая защиту от скрытия формул; TXLSGetPivotTable и OnGetPivotTable находят заимствованную таблицу по однобазовому SheetIndex и базирующимся на нуле координатам диапазона

Движки книг подключают эти необязательные callback в обычном, read-only и изолированном контекстах вычислений; callback не пересчитывают цели, не обновляют источники Pivot и не передают владение

TXLSPivotDataConstraint хранит FieldName и типизированный Item, при этом TXLSPivotDataConstraints собирает пары поле/элемент; TXLSPivotTable.GetDataValue запрашивает один видимый поддерживаемый агрегат из отсоединённого снимка локальной таблицы/кэша, а IntersectsQueryRange использует однобазовые границы листа, включая смоделированные ячейки фильтра отчёта

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

TXLSPivotCache.QueryModelIsComplete фиксирует готовность декодированного запроса независимо от полноты сырого воспроизведения BIFF; QueryRecordsValid открывает валидность импортированных записей, а SetQueryRecordValidity применяет приоритет читателя формата, не обновляя записи

Явные байты кодовых страниц

Передавайте возвращённый RawByteString напрямую в AddRawString или байтово-ориентированную операцию с потоком; преобразование его в AnsiString по умолчанию может перекодировать его байты на нативных системах FPC

Классические определённые имена и блоки формул массива

Классические пулы шрифтов, форматов и стилей

Вспомогательные средства пакета и двоичного хранилища

Дополнения для рисования и средства просмотра книг

Разбивка на страницы, вывод изображений и печать

Модели классических диаграмм и объекты диаграмм на листе

Типизированная модель декодирования диаграмм

Декодированное состояние диаграммы открывается как обычные записи и перечисления, чтобы код осмотра никогда не разбирал необработанные записи BIFF вручную: TXLSChartInfo несёт сводку декодированной диаграммы с TXLSChartTypeFamily (cfBar, cfLine, cfPie, cfArea, cfScatter, cfRadar, cfDoughnut, cfSurface, cfBubble), каждый ряд сообщает TXLSChartSeriesType, а TXLSChart3DState вместе с TXLSChart3DInfo описывают трёхмерные виды. TXLSChartAxisType (catCategory, catValue, catSeries, catDate) и TXLSChartLegendPosition классифицируют оси и легенды, а модель оси дат использует TXLSChartDateUnit (xcduDays, xcduMonths, xcduYears) и TXLSChartDateValues. TXLSCustomChart открывает декодированную модель через TXLSChartInfo; аннотации линий тренда и планок погрешностей — типизированные объекты (TXLSChartTrendline, TXLSChartErrorBars), доступные от каждого ряда

Записи создания диаграмм

Создание листов диаграмм и работа через построитель принимают обычные записи вместо графов объектов: TXLSChartTrendlineInfo, TXLSChartErrorBarsInfo, TXLSChartDataLabelsInfoи TXLSChartSeriesStyleInfo заполняют элементы рядов, передаваемые в TXLSWorksheets.AddChartSheet и общий построитель диаграмм, а TXLSPivotChartInfo описывает обрамление сводной диаграммы, используемое, когда диаграмма привязывается к сводной таблице

Осмотр заливки классических диаграмм

TXLSCustomChart.GetChartModel декодирует поддерживаемые нативные таблицы свойств OfficeArt и третичные таблицы свойств в записях GelFrame, включая свойства после записей со сложными полезными нагрузками; существующее представление построителя остаётся поддерживаемым, а некорректные границы таблиц оставляют прежнюю типизированную заливку неизменной и сообщают о неподдерживаемой записи

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

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

Ограниченные читатели сохранённых диаграмм, строк и шрифтов

TXLSChartStoredBytes — отсоединённый байтовый массив, а TXLSChartStoredRecord содержит RecordIdи Data; эти читатели осматривают удерживаемое исходное хранилище, не создавая декодированную модель диаграммы и не вычисляя формулы

Обслуживание таблицы общих строк и вывод SST

TXLSStringTable в lxStringTable поддерживает общие строки классической книги; члены ниже покрывают регистрацию на стороне читателя, обслуживание слотов и сырой вывод SST для сохранений с полным roundtrip

Вложения PDF, подписи и экспорт HTML

Аудит вычислений и элементы управления книги

Совместимость устаревшего обрамления PivotCache

StreamId записывается как запись SXStreamID ([MS-XLS] §2.4.303) и повторяется как поле SXDB заголовка idstm , которое должно ему равняться; SourceDataType записывается как запись SXVS ([MS-XLS] §2.4.317: $0001 — лист, $0002 — внешняя, $0004 — консолидация, $0010 — сценарий) и повторяется как поле SXDB заголовка vsType , которое должно ему равняться. Кэши, построенные по диапазону листа, начинаются с типа «лист», а кэши, прочитанные из файла, сохраняют значение, которое нёс их подпоток, поэтому BIFF-писатель никогда не оставляет в поле SXDB имя записи, которую он не записывал; RawHasStorageStream помечает кэш, загруженный из собственного потока хранилища, общекнижный дескриптор которого предшествует кэшированным записям

Интеграция с буфером обмена и параметры вставки

TXLSPasteOption = (xlpoValuesOnly, xlpoInsertRows, xlpoInsertCols);
TXLSPasteOptions = set of TXLSPasteOption;

function XLSGetClipboardText: WideString;
function XLSSetClipboardText(const Text: WideString): Boolean;
function XLSSetClipboardTextAndHtml(const Text: WideString;
  const Html: AnsiString): Boolean;
function XLSBuildHtmlClipboard(const Html: AnsiString): AnsiString;
function XLSEncodeClipboardField(const Text: WideString): WideString;
function XLSClipboardHasText: Boolean;
function XLSParseClipboardGrid(const ClipboardText: WideString;
  Loader: TXLSCSVLoader): Boolean;
function XLSClipboardHasXmlSpreadsheet: Boolean;
function XLSGetClipboardXmlSpreadsheet: WideString;
function XLSParseXmlSpreadsheet(const XmlText: WideString;
  Loader: TXLSCSVLoader): Boolean;
function XLSClipboardHasBiff8: Boolean;
function XLSGetClipboardBiff8: AnsiString;
function XLSReadClipboardPasteData(out Biff8: AnsiString;
  out Text: WideString): Boolean;
function XLSSetClipboardBiff8(const Biff8: AnsiString;
  const Text: WideString; const Html: AnsiString = ''): Boolean;
      

Разрешение отображаемого текста ячейки

TXLSCellDisplayMode = (xcdmFormattedValue, xcdmFormulaText,
  xcdmSuppressedZero);

TXLSCellDisplayOptions = record
  ShowFormulas: Boolean;
  ShowZeros: Boolean;
  SheetProtected: Boolean;
  FormulaWidthFactor: Double;
  DateSerialZero: Double;
end;

TXLSCellDisplayInput = record
  HasFormula: Boolean;
  FormulaHidden: Boolean;
  IsNumericZero: Boolean;
  FormulaText: WideString;
  FormattedText: WideString;
end;

TXLSCellDisplayResult = record
  Mode: TXLSCellDisplayMode;
  Text: WideString;
  TreatAsText: Boolean;
  EffectiveWidthFactor: Double;
end;

function XLSDefaultCellDisplayOptions: TXLSCellDisplayOptions;
function XLSNormalizeFormulaDisplayText(const FormulaText: WideString): WideString;
function XLSResolveCellDisplay(const Options: TXLSCellDisplayOptions;
  const Input: TXLSCellDisplayInput): TXLSCellDisplayResult;
      

Объекты классической проверки данных

TXLSDataValidationType = (xlsDvAny, xlsDvWhole, xlsDvDecimal, xlsDvList,
  xlsDvDate, xlsDvTime, xlsDvTextLength, xlsDvCustom);
TXLSDvErrorStyle = (xlsDvErrStop, xlsDvErrWarning, xlsDvErrInformation);

TDVRange = class;             { one validation rule over one or more ranges }
TDVRangeList = class;         { the per-sheet rule collection }
TDataValidator = class;       { engine that checks edits against the rules }
      

Сканирование и разрешение индексированных цветов

TXLSIndexedColorKind = (xickPalette, xickAutomatic, xickSystem, xickInvalid);
TXLSSystemColorRole = (xscrNone, xscrWindowText, xscrWindowBackground,
  xscrChartText, xscrChartBackground, xscrChartNeutral, xscrToolTipText);

TXLSIndexedColorResolution = record
  Kind: TXLSIndexedColorKind;
  RawIndex: Int64;
  PaletteSlot: Integer;
  SystemColorRole: TXLSSystemColorRole;
  ARGB: LongWord;
  HasResolvedColor: Boolean;
end;

TXLSNearestIndexedColorMatch = record
  InputARGB: LongWord;
  ColorIndex: Integer;
  PaletteSlot: Integer;
  ARGB: LongWord;
  DistanceSquared: Double;
  ExactMatch: Boolean;
end;

TXLSIndexedColorUsageKind = (xicukFont, xicukFillForeground,
  xicukFillBackground, xicukGradient, xicukBorder, xicukConditionalFormat,
  xicukChart, xicukShape, xicukComment, xicukWorksheet, xicukOther);
      

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

function XLSA1CellRef(ARow, ACol: Integer): WideString;
function XLSTryParseA1CellRef(const ARef: WideString;
  out ARow, ACol: Integer): Boolean;
function XLSTryParseA1RangeRef(const ARef: WideString;
  out ARow1, ACol1, ARow2, ACol2: Integer): Boolean;
      

См. также

• Дополнительные члены классического XLS API
• Расширенные члены API XLSX
• Разреженная геометрия структуры
• Трассировка и аудит формул
• Просмотр книг