Методы SaveSemanticSnapshot и ComputeSemanticHash

Выполняет потоковую запись версионируемого канонического представления семантики книги или вычисляет SHA-256 ровно этих байтов

Синтаксис

procedure SaveSemanticSnapshot(AStream: TStream); overload;
procedure SaveSemanticSnapshot(AStream: TStream;
  AProfile: TXLSSemanticSnapshotProfile;
  AOptions: TXLSSemanticSnapshotOptions); overload;

function ComputeSemanticHash: WideString; overload;
function ComputeSemanticHash(
  AProfile: TXLSSemanticSnapshotProfile;
  AOptions: TXLSSemanticSnapshotOptions): WideString; overload;

Методы предоставляются классическими IXLSWorkbook и TXLSWorkbook в lxHandle, а также TXLSXWorkbook в lxHandleX

Типы профиля и параметров объявлены в lxSemanticSnapshot и видны через оба модуля книги

Профили

Параметры

Перегрузки без параметров используют TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOptionс пустым набором параметров xlsspContent with an empty option set

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

• SaveSemanticSnapshot выполняет запись в текущую позицию целевого потока и не выполняет позиционирование, не владеет потоком и не освобождает его
• Сбой записи ниже по потоку может оставить начальный фрагмент в целевом объекте, поэтому вызывающим сторонам, которым требуется атомарная публикация, следует сначала выполнять запись во временный целевой объект, а затем заменять окончательное назначение
• ComputeSemanticHash возвращает 64 строчных шестнадцатеричных символа и вычисляет хеш инкрементально, не выделяя полный буфер снимка
• Снимок — это семантический протокол HotXLS, а не документ XLS, XLSX, ODS, CSV или PDF
• Сравнивайте снимки или хеши только при совпадении версии протокола, профиля и набора параметров
• Операция не сохраняет, не пересчитывает, не обновляет ссылки, не обращается к внешним ресурсам и не изменяет кэши книги

Современные функции ячеек

TXLSSemanticCellStyle.CellControlKind имеет тип TXLSSemanticCellControlKind со значениями xlssControlNone, xlssControlUnknown и xlssControlCheckbox; CellControlDefaultState имеет тип TXLSSemanticCheckboxDefaultState со значениями xlssCheckboxUnchecked, xlssCheckboxChecked и xlssCheckboxBlank

Чтение стилей XLSX разрешает прямые и унаследованные контролы без создания ячеек; каноническая сериализация стилей отклоняет xlssControlUnknown, вместо того чтобы считать неизвестный набор свойств обычной ячейкой

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

TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) возвращает отсоединённые записи, ключом которых служит адрес ячейки, включая точные закодированные байты PNG или JPEG, тип содержимого, альтернативный текст и метаданные decorative; квоты покрывают канонические байты и записи изображений, а слишком большие полезные нагрузки отклоняются до копирования

При сравнении книг эти определения изображений включаются, когда выбран lcoDrawings, а lcoCellStyles и lcoBlankStyleRegions включают эффективные форматы Checkbox; одного лишь совпадения запасных ошибок недостаточно, чтобы считать разные изображения равными

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

Конкурентность и ошибки

Оба метода удерживают аренду чтения книги на время всего обхода

Одновременная публичная модификация завершается сбоем с EXLSWorkbookWriteGuardUnavailableдо изменения состояния книги, тогда как обнаруженное изменение поколения или неподдерживаемая неоднозначная семантическая структура вызывает EXLSSemanticSnapshot

Пример для Delphi

var
  Snapshot: TFileStream;
  Hash: WideString;
begin
  Snapshot:= TFileStream.Create('workbook.semantic', fmCreate);
  try
    Workbook.SaveSemanticSnapshot(Snapshot,
      xlsspSecurityComplete,
      [xlssoIncludeFormulaCachedResults]);
  finally
    Snapshot.Free;
  end;

  Hash:= Workbook.ComputeSemanticHash;

Пример для C++Builder

TFileStream *snapshot = new TFileStream(
  L"workbook.semantic", fmCreate);
try
{
  workbook->SaveSemanticSnapshot(snapshot);
}
__finally
{
  delete snapshot;
}

WideString hash = workbook->ComputeSemanticHash();

См. также

Движок снимков не привязан к объектам книги: всё перечисленное ниже объявлено в lxSemanticSnapshot, а методы книги — тонкие обёртки над теми же глобальными точками входа

Extension interfaces

Implement IXLSSemanticWorkbookSource чтобы выдавать или хэшировать снимок любого источника, и опционально IXLSSemanticFormulaResolver чтобы выдаваемые формулы несли разрешённую информацию о внешних ссылках и определённых именах

IXLSSemanticWorkbookSource = interface
  procedure WriteCommon(AWriter: TXLSSemanticCanonicalWriter);
end;

IXLSSemanticFormulaResolver = interface
  function ResolveFormulaReference(AExternID: Integer;
    out AInfo: TXLSSemanticFormulaReferenceInfo): Boolean;
  function ResolveFormulaName(ANameID, AExternID: Integer;
    out AInfo: TXLSSemanticFormulaNameInfo): Boolean;
end;

TXLSSemanticFormulaReferenceInfo = record
  LinkKind: TXLSSemanticFormulaLinkKind;
  BookName: WideString;
  FirstSheetName: WideString;
  LastSheetName: WideString;
end;

TXLSSemanticFormulaNameInfo = record
  NameKind: TXLSSemanticFormulaNameKind;
  LinkKind: TXLSSemanticFormulaLinkKind;
  Name: WideString;
  ScopeSheetName: WideString;
  BookName: WideString;
end;

Inside WriteCommon писатель — непрозрачный дескриптор: не вызывайте его примитивные методы — BeginContainer / EndContainer frame a tagged container and WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideString, and WriteBytes кодируют по одному каноническому примитиву, причём Finish sealing the stream and Finished сообщает о завершении — передавайте его обратно в хелперы выдачи ниже, чтобы каждый производитель выдавал идентичные байты

Entry-point globals

procedure XLSSaveSemanticSnapshot(AStream: TStream;
  const ASource: IXLSSemanticWorkbookSource;
  AProfile: TXLSSemanticSnapshotProfile;
  AOptions: TXLSSemanticSnapshotOptions);
function XLSComputeSemanticHash(
  const ASource: IXLSSemanticWorkbookSource;
  AProfile: TXLSSemanticSnapshotProfile;
  AOptions: TXLSSemanticSnapshotOptions): WideString;
procedure XLSInitializeSemanticCellStyle(out AStyle: TXLSSemanticCellStyle);
function XLSBuiltinSemanticNumberFormat(AId: Word): WideString;

XLSInitializeSemanticCellStyle заполняет запись стиля каноническими значениями по умолчанию до правки отдельных полей; XLSBuiltinSemanticNumberFormat отображает встроенный id числового формата (ниже 164) в его строку формата, что потребителям нужно для интерпретации выданных стилей и декодированных потоков

Model vocabulary

Emission helpers

Эти глобальные функции записывают один фрагмент модели в писатель, переданный в WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinition, and XLSWriteSemanticFormulaCell (ячейки с формулами несут границы массива и опциональный кэшированный результат). XLSWriteSemanticWorkbookCommon открывает контейнер книги и вызывает WriteCommon, который пользовательские источники обычно вызывают первым

See also

Интерфейс IXLSWorkbook · Класс TXLSXWorkbook · Метод CreateReadOnlyView