Métodos SaveSemanticSnapshot y ComputeSemanticHash

Transmite por secuencias una representación canónica con versión de la semántica del libro de trabajo o calcula el SHA-256 de exactamente esos bytes

Sintaxis

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;

Los métodos los exponen el IXLSWorkbook y el TXLSWorkbook clásicos en lxHandle, y TXLSXWorkbook en lxHandleX

Los tipos de perfil y de opciones se declaran en lxSemanticSnapshot y son visibles a través de ambas unidades del libro de trabajo

Perfiles

Opciones

El conjunto de opciones tiene el tipo TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOption; las sobrecargas sin parámetros usan xlsspContent con un conjunto de opciones vacío

Reglas de streaming e identidad

• SaveSemanticSnapshot escribe en la posición actual del flujo de destino y no busca en él, no es su propietario ni lo libera
• Un error de escritura aguas abajo puede dejar un prefijo en el destino, por lo que los llamadores que requieran publicación atómica deben escribir en un destino temporal antes de reemplazar el destino definitivo
• ComputeSemanticHash devuelve 64 caracteres hexadecimales en minúsculas y calcula el hash de forma incremental sin asignar un búfer completo para la instantánea
• La instantánea es un protocolo semántico de HotXLS, no un documento XLS, XLSX, ODS, CSV ni PDF
• Compare instantáneas o hashes solo cuando coincidan la versión del protocolo, el perfil y el conjunto de opciones
• La operación no guarda, no recalcula, no actualiza vínculos, no accede a recursos externos ni muta las cachés del libro de trabajo

Funciones modernas de celda

TXLSSemanticCellStyle.CellControlKind tiene el tipo TXLSSemanticCellControlKind con xlssControlNone, xlssControlUnknown y xlssControlCheckbox; CellControlDefaultState tiene el tipo TXLSSemanticCheckboxDefaultState con xlssCheckboxUnchecked, xlssCheckboxChecked y xlssCheckboxBlank

Las lecturas de estilos XLSX resuelven controles directos y heredados sin crear celdas; la serialización canónica de estilos rechaza xlssControlUnknown en lugar de tratar un property bag desconocido como una celda plana

Las instantáneas y los hashes incluyen rectángulos de control efectivos normalizados, combinando regiones contiguas iguales sin expandir columnas completas en celdas; los overlays de estilo ajenos no predeterminados conservan su frontera existente de normalización no soportada

TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) devuelve entradas separadas indexadas por dirección de celda, incluidos los bytes PNG o JPEG codificados exactos, el tipo de contenido, el texto alternativo y los metadatos decorativos; las cuotas cubren los bytes canónicos y las entradas de imagen, y las cargas útiles demasiado grandes se rechazan antes de copiar

La comparación de libros incluye estas definiciones de imagen cuando se selecciona lcoDrawings, mientras que lcoCellStyles y lcoBlankStyleRegions incluyen los formatos Checkbox efectivos; que los errores de respaldo coincidan solos no hace iguales dos imágenes distintas

Los grafos de imagen de rich value desconocidos lanzan EXLSSemanticSnapshot durante la comparación de funciones seleccionada o el recorrido de la instantánea; estas operaciones retienen la concesión de lectura del libro y no calculan las celdas inspeccionadas

Concurrencia y errores

Ambos métodos mantienen una concesión de lectura del libro de trabajo durante todo el recorrido

Una mutación pública simultánea falla antes de cambiar el estado del libro de trabajo con EXLSWorkbookWriteGuardUnavailable, mientras que un cambio de generación detectado o una estructura semántica ambigua no admitida genera EXLSSemanticSnapshot

Ejemplo de 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;

Ejemplo de C++Builder

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

WideString hash = workbook->ComputeSemanticHash();

Referencia del modelo de instantáneas

El motor de instantáneas no está ligado a los objetos del libro de trabajo: todo lo siguiente se declara en lxSemanticSnapshot, y los métodos del libro de trabajo son envoltorios ligeros sobre los mismos puntos de entrada globales

Interfaces de extensión

Implemente IXLSSemanticWorkbookSource para emitir o calcular el hash de una instantánea de cualquier origen y, opcionalmente, IXLSSemanticFormulaResolver para que las fórmulas emitidas incluyan información resuelta de referencias externas y nombres 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 el escritor es un manejador opaco: no llame a sus métodos primitivos — BeginContainer / EndContainer enmarcan un contenedor etiquetado y WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideStringy WriteBytes codifican una primitiva canónica cada uno, con Finish sellando el flujo y Finished informando la finalización — páseselo de vuelta a los auxiliares de emisión de abajo para que cada productor emita bytes idénticos

Globales de punto 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 rellena un registro de estilo con los valores predeterminados canónicos antes de editar campos individuales; XLSBuiltinSemanticNumberFormat asigna un id de formato numérico integrado (menor que 164) a su cadena de formato, que los consumidores necesitan para interpretar los estilos emitidos y los flujos decodificados

Vocabulario del modelo

Auxiliares de emisión

Estos globales escriben un fragmento del modelo en el escritor que se pasa a WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinitiony XLSWriteSemanticFormulaCell (las celdas de fórmula llevan los límites de la matriz y un resultado en caché opcional). XLSWriteSemanticWorkbookCommon abre el contenedor del libro de trabajo e invoca WriteCommon, que las fuentes personalizadas normalmente invocan primero

Véase también

Interfaz IXLSWorkbook · Clase TXLSXWorkbook · Método CreateReadOnlyView