Métodos SaveSemanticSnapshot e ComputeSemanticHash

Transmite em fluxo uma representação canônica com versão da semântica da pasta de trabalho ou calcula o SHA-256 de exatamente esses bytes

Sintaxe

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;

Os métodos são expostos pelo IXLSWorkbook e pelo TXLSWorkbook clássicos em lxHandlee pelo TXLSXWorkbook em lxHandleX

Os tipos de perfil e de opções são declarados em lxSemanticSnapshot e ficam visíveis por meio de ambas as unidades da pasta de trabalho

Perfis

Opções

The option set has type TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOptionAs sobrecargas sem parâmetros usam xlsspContent com um conjunto de opções vazio

Regras de fluxo e de identidade

• SaveSemanticSnapshot grava na posição atual do fluxo de destino e não busca, não assume a propriedade e não libera o fluxo
• Uma falha de gravação a jusante pode deixar um prefixo no destino, de modo que chamadores que exigem publicação atômica devem gravar em um destino temporário antes de substituir o destino final
• ComputeSemanticHash retorna 64 caracteres hexadecimais minúsculos e calcula o hash incrementalmente sem alocar um buffer completo para o instantâneo
• O instantâneo é um protocolo semântico do HotXLS, não um documento XLS, XLSX, ODS, CSV nem PDF
• Compare instantâneos ou hashes somente quando a versão do protocolo, o perfil e o conjunto de opções coincidirem
• A operação não salva, não recalcula, não atualiza links, não acessa recursos externos e não modifica os caches da pasta de trabalho

Recursos modernos de célula

TXLSSemanticCellStyle.CellControlKind tem o tipo TXLSSemanticCellControlKind com xlssControlNone, xlssControlUnknowne xlssControlCheckbox; CellControlDefaultState tem o tipo TXLSSemanticCheckboxDefaultState com xlssCheckboxUnchecked, xlssCheckboxCheckede xlssCheckboxBlank

As leituras de estilo XLSX resolvem controles diretos e herdados sem criar células; a serialização canônica de estilos rejeita xlssControlUnknown em vez de tratar um property bag desconhecido como uma célula comum

Snapshots e hashes incluem retângulos efetivos de controle normalizados, mesclando regiões adjacentes iguais sem expandir colunas inteiras em células; overlays de estilo não padrão não relacionados retêm seu limite existente de normalização sem suporte

TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) retorna entradas destacadas chaveadas por endereço de célula, incluindo os bytes exatos codificados de PNG ou JPEG, o tipo de conteúdo, o texto alternativo e metadados decorativos; as quotas cobrem bytes canônicos e entradas de imagem, e payloads grandes demais são rejeitados antes da cópia

A comparação de pastas de trabalho inclui essas definições de imagem quando lcoDrawings está selecionado, enquanto lcoCellStyles e lcoBlankStyleRegions incluem os formatos efetivos de Checkbox; erros de fallback correspondentes, sozinhos, não tornam imagens distintas iguais

Grafos de imagem de rich value desconhecidos geram EXLSSemanticSnapshot durante a comparação de recursos selecionados ou a travessia de snapshot; essas operações retêm a concessão de leitura da pasta de trabalho e não calculam as células inspecionadas

Simultaneidade e erros

Ambos os métodos mantêm uma concessão de leitura da pasta de trabalho durante toda a travessia

Uma mutação pública simultânea falha antes de alterar o estado da pasta de trabalho com EXLSWorkbookWriteGuardUnavailable, enquanto uma mudança de geração detectada ou uma estrutura semântica ambígua sem suporte gera EXLSSemanticSnapshot

Exemplo em 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;

Exemplo em C++Builder

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

WideString hash = workbook->ComputeSemanticHash();

Referência do modelo de snapshot

O motor de snapshot não está ligado aos objetos da pasta de trabalho: tudo abaixo é declarado em lxSemanticSnapshot, e os métodos da pasta de trabalho são wrappers finos sobre os mesmos pontos de entrada globais

Interfaces de extensão

Implemente IXLSSemanticWorkbookSource para emitir ou calcular o hash de um snapshot de qualquer origem e, opcionalmente, IXLSSemanticFormulaResolver para que as fórmulas emitidas carreguem informações resolvidas de referências externas e nomes definidos

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;

Dentro de WriteCommon o writer é um handle opaco: não chame seus métodos primitivos — BeginContainer / EndContainer delimitam um container tagado e WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideStringe WriteBytes codificam um primitivo canônico cada, com Finish selando o stream e Finished informando a conclusão — passe-o de volta para os helpers de emissão abaixo para que todo produtor emita bytes idênticos

Globais de ponto de entrada

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 preenche um record de estilo com os padrões canônicos antes que campos individuais sejam editados; XLSBuiltinSemanticNumberFormat mapeia um id de formato numérico builtin (abaixo de 164) para sua string de formato, que os consumidores precisam para interpretar estilos emitidos e streams decodificados

Vocabulário do modelo

Helpers de emissão

Esses globais gravam um fragmento do modelo no writer passado a WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinitione XLSWriteSemanticFormulaCell (células de fórmula carregam limites de matriz e um resultado em cache opcional). XLSWriteSemanticWorkbookCommon abre o container da pasta de trabalho e invoca WriteCommon, que fontes personalizadas normalmente chamam primeiro

Veja também

Interface IXLSWorkbook · Classe TXLSXWorkbook · Método CreateReadOnlyView