Métodos SaveSemanticSnapshot y ComputeSemanticHash

Transmite por secuencias una representación canónica con versión de la semántica del libro 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

Perfiles

Opciones

The option set has type TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOptionLas sobrecargas sin parámetros usan xlsspContent con un conjunto de opciones vacío

Reglas de secuenciación e identidad

• SaveSemanticSnapshot escribe en la posición actual del flujo de destino y no busca en él, no lo posee 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

Características 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 una bolsa de propiedades desconocida como una celda corriente

Las instantáneas y los hashes incluyen rectángulos de control efectivos normalizados, fusionando regiones iguales adyacentes sin expandir columnas completas en celdas; las superposiciones de estilo no predeterminadas no relacionadas conservan su límite existente de normalización no admitida

TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) devuelve entradas desacopladas indexadas por dirección de celda, incluidos los bytes exactos codificados en PNG o JPEG, 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 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 efectivos de casilla; que solo coincidan los errores de reserva no hace que imágenes distintas sean iguales

Los grafos de imágenes de valor enriquecido desconocidos generan EXLSSemanticSnapshot durante la comparación de características seleccionada o el recorrido de la instantánea; estas operaciones conservan 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 durante todo el recorrido

Una mutación pública simultánea falla antes de cambiar el estado del libro 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ánea

El motor de instantáneas no está ligado a los objetos del libro de trabajo: todo lo que sigue está declarado en lxSemanticSnapshot, y los métodos del libro 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 fuente y, opcionalmente, IXLSSemanticFormulaResolver para que las fórmulas emitidas lleven 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 cada uno una primitiva canónica, con Finish sellando el flujo y Finished informando de la finalización — páseselo de vuelta a los asistentes 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 mapea un identificador de formato de número integrado (por debajo de 164) a su cadena de formato, que los consumidores necesitan para interpretar los estilos emitidos y los flujos decodificados

Vocabulario del modelo

Asistentes de emisión

Estos globales escriben un fragmento del modelo en el escritor pasado a WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinitiony XLSWriteSemanticFormulaCell (las celdas de fórmula llevan límites de array y un resultado cacheado opcional). XLSWriteSemanticWorkbookCommon abre el contenedor del libro e invoca WriteCommon, que las fuentes personalizadas normalmente llaman primero

Véase también

Interfaz IXLSWorkbook · Clase TXLSXWorkbook · Método CreateReadOnlyView