SaveSemanticSnapshot- und ComputeSemanticHash-Methoden

Streamt eine versionierte kanonische Repräsentation der Arbeitsmappensemantik oder berechnet den SHA-256 genau dieser Bytes

Syntax

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;

Die Methoden werden von klassischem IXLSWorkbook und TXLSWorkbook in lxHandlesowie von TXLSXWorkbook in lxHandleX

Die Profil- und Optionstypen sind in lxSemanticSnapshot deklariert und über beide Arbeitsmappen-Units sichtbar

Profile

Optionen

Die Überladungen ohne Parameter verwenden TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOptionmit einer leeren Optionensammlung xlsspContent with an empty option set

Streaming- und Identitätsregeln

• SaveSemanticSnapshot schreibt an der aktuellen Position des Ziel-Streams und verschiebt den Stream nicht, übernimmt ihn nicht und gibt ihn nicht frei
• Ein nachgelagerter Schreibfehler kann ein Präfix im Ziel hinterlassen, daher sollten Aufrufer, die atomare Veröffentlichung benötigen, zunächst in ein temporäres Ziel schreiben, bevor sie das Ziel ersetzen
• ComputeSemanticHash gibt 64 kleingeschriebene hexadezimale Zeichen zurück und hashed inkrementell, ohne einen vollständigen Schnappschuss-Puffer zuzuweisen
• Der Schnappschuss ist ein HotXLS-Semantikprotokoll, kein XLS-, XLSX-, ODS-, CSV- oder PDF-Dokument
• Vergleichen Sie Schnappschüsse oder Hashes nur, wenn Protokollversion, Profil und Optionensammlung übereinstimmen
• Die Operation speichert nicht, berechnet nicht neu, aktualisiert keine Links, greift nicht auf externe Ressourcen zu und verändert keine Arbeitsmappen-Caches

Moderne Zellfeatures

TXLSSemanticCellStyle.CellControlKind hat den Typ TXLSSemanticCellControlKind mit xlssControlNone, xlssControlUnknown und xlssControlCheckbox; CellControlDefaultState hat den Typ TXLSSemanticCheckboxDefaultState mit xlssCheckboxUnchecked, xlssCheckboxChecked und xlssCheckboxBlank

XLSX-Stil-Lesevorgänge lösen direkte und geerbte Controls auf, ohne Zellen zu erzeugen; die kanonische Stilserialisierung weist xlssControlUnknown zurück, statt eine unbekannte Property-Bag als einfache Zelle zu behandeln

Snapshots und Hashes schließen normalisierte effektive Control-Rechtecke ein und verschmelzen benachbarte gleiche Regionen, ohne ganze Spalten in Zellen auszurollen; nicht verwandte Nicht-Default-Stil-Overlays behalten ihre bisherige Grenze der nicht unterstützten Normalisierung

TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) liefert entkoppelte Einträge mit der Zelladresse als Schlüssel, einschließlich exakter kodierter PNG- oder JPEG-Bytes, Content-Type, alternativem Text und Decorative-Metadaten; die Quotas decken kanonische Bytes und Bildeinträge ab, und überdimensionierte Payloads werden vor dem Kopieren zurückgewiesen

Der Arbeitsmappenvergleich schließt diese Bilddefinitionen ein, wenn lcoDrawings gewählt ist, während lcoCellStyles und lcoBlankStyleRegions effektive Checkbox-Formate einschließen; allein übereinstimmende Fallback-Fehler machen unterschiedliche Bilder nicht gleich

Unbekannte Rich-Value-Bildgraphen lösen während ausgewählter Feature-Vergleiche oder der Snapshot-Traversierung EXLSSemanticSnapshot aus; diese Operationen halten die Leselease der Arbeitsmappe und berechnen keine untersuchten Zellen

Nebenläufigkeit und Fehler

Beide Methoden halten für die gesamte Traversierung eine Leselease der Arbeitsmappe

Eine gleichzeitige öffentliche Mutation schlägt fehl, bevor der Arbeitsmappenzustand verändert wird, mit EXLSWorkbookWriteGuardUnavailable, während eine erkannte Generationsänderung oder eine nicht unterstützte mehrdeutige semantische Struktur EXLSSemanticSnapshot

Delphi-Beispiel

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-Beispiel

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

WideString hash = workbook->ComputeSemanticHash();

Referenz des Snapshot-Modells

Die Snapshot-Engine ist nicht an Arbeitsmappenobjekte gebunden: Alles Folgende ist in lxSemanticSnapshotdeklariert, und die Arbeitsmappen-Methoden sind dünne Wrapper über dieselben globalen Einstiegspunkte

Erweiterungs-Schnittstellen

Implementieren Sie IXLSSemanticWorkbookSource , um einen Snapshot einer beliebigen Quelle zu emittieren oder zu hashen, und optional IXLSSemanticFormulaResolver , damit emittierte Formeln aufgelöste External-Reference- und Defined-Name-Informationen tragen

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;

Innerhalb von WriteCommon ist der Writer ein opakes Handle: Rufen Sie seine primitiven Methoden nicht direkt auf — BeginContainer / EndContainer rahmen einen getaggten Container ein, und WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideStringund WriteBytes kodieren je genau ein kanonisches Primitiv, während Finish den Stream versiegelt und Finished die Fertigstellung meldet — reichen Sie ihn an die unten stehenden Emissions-Helper weiter, damit jeder Producer identische Bytes emittiert

Globale Einstiegspunkte

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 füllt einen Style-Datensatz mit den kanonischen Defaults, bevor einzelne Felder bearbeitet werden; XLSBuiltinSemanticNumberFormat bildet eine eingebaute Zahlenformat-ID (unter 164) auf ihren Format-String ab, den Consumer brauchen, um emittierte Styles und dekodierte Streams zu interpretieren

Modell-Vokabular

Emissions-Helper

Diese globalen Funktionen schreiben je ein Modellfragment in den Writer, der an WriteCommonübergeben wird: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinitionund XLSWriteSemanticFormulaCell (Formelzellen tragen Array-Grenzen und ein optionales zwischengespeichertes Ergebnis). XLSWriteSemanticWorkbookCommon öffnet den Arbeitsmappen-Container und ruft WriteCommonauf — was benutzerdefinierte Quellen normalerweise zuerst aufrufen

Siehe auch

IXLSWorkbook-Schnittstelle · TXLSXWorkbook-Klasse · CreateReadOnlyView-Methode