Metoderna SaveSemanticSnapshot och ComputeSemanticHash

Skriver en versionsmärkt kanonisk representation av arbetsbokens semantik till en ström, eller beräknar SHA-256 av exakt de byte

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;

Metoderna exponeras av Classic IXLSWorkbook och TXLSWorkbook i lxHandle och av TXLSXWorkbook i lxHandleX

Profil- och alternativtyperna deklareras i lxSemanticSnapshot och är synliga via båda arbetsboksenheterna

Profiler

Alternativ

Alternativuppsättningen har typen TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOption. Överlagringarna utan parametrar använder xlsspContent med en tom alternativuppsättning

Regler för ström och identitet

• SaveSemanticSnapshot skriver vid målströmmens aktuella position och utför ingen sökning, tar inte ägarskap för och frigör inte strömmen
• En nedströms skrivfel kan lämna ett prefix i målet, så anropare som kräver atomär publicering bör skriva till ett tillfälligt mål innan destinationen ersätts
• ComputeSemanticHash returnerar 64 gemena hexadecimala tecken och beräknar hashen inkrementellt utan att allokera en komplett ögonblicksbildbuffert
• Ögonblicksbilden är ett semantiskt HotXLS-protokoll, inte ett XLS-, XLSX-, ODS-, CSV- eller PDF-dokument
• Jämför ögonblicksbilder eller hashar endast när protokollversion, profil och alternativuppsättning matchar
• Operationen sparar inte, räknar inte om, uppdaterar inte länkar, öppnar inte externa resurser och muterar inte arbetsbokens cacher

Moderna cellfunktioner

TXLSSemanticCellStyle.CellControlKind har typen TXLSSemanticCellControlKind med xlssControlNone, xlssControlUnknown och xlssControlCheckbox; CellControlDefaultState har typen TXLSSemanticCheckboxDefaultState med xlssCheckboxUnchecked, xlssCheckboxChecked och xlssCheckboxBlank

XLSX-stilläsningar löser upp direkta och ärvda kontroller utan att skapa celler; kanonisk stilserialisering avvisar xlssControlUnknown i stället för att behandla en okänd egenskapspåse som en vanlig cell

Ögonblicksbilder och hashar inkluderar normaliserade effektiva kontrollrektanglar och slår samman intilliggande lika regioner utan att expandera hela kolumner till celler; orelaterade icke-standard-stilöverlägg behåller sin befintliga gräns för ostödd normalisering

TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) returnerar fristående poster nycklade efter celladress, inklusive exakta kodade PNG- eller JPEG-byte, innehållstyp, alternativtext och dekorativ metadata; kvoterna täcker kanoniska byte och bildposter, och överdimensionerade nyttolaster avvisas före kopiering

Arbetsboksjämförelsen inkluderar dessa bilddefinitioner när lcoDrawings är valt, medan lcoCellStyles och lcoBlankStyleRegions inkluderar effektiva Checkbox-format; enbart matchande reservfel gör inte distinkta bilder lika

Okända grafer av riktvärdebilder utlöser EXLSSemanticSnapshot under jämförelse av utvalda funktioner eller genomlopp av ögonblicksbilden; dessa operationer behåller arbetsbokens läslån och beräknar inte de granskade cellerna

Samtidighet och fel

Båda metoderna håller en läslåneperiod på arbetsboken under hela genomloppet

En samtidig offentlig mutation misslyckas innan arbetsbokens tillstånd ändras, med EXLSWorkbookWriteGuardUnavailable, medan en upptäckt generationsändring eller en ej stödd tvetydig semantisk struktur utlöser EXLSSemanticSnapshot

Delphi-exempel

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

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

WideString hash = workbook->ComputeSemanticHash();

Referens för ögonblicksbildsmodellen

Ögonblicksbildsmotorn är inte knuten till arbetsboksobjekt: allt nedan deklareras i lxSemanticSnapshot, och arbetsboksmetoderna är tunna omslag över samma globala startpunkter

Utökningsgränssnitt

Implementera IXLSSemanticWorkbookSource för att emittera eller hasha en ögonblicksbild av valfri källa, och valfritt IXLSSemanticFormulaResolver så att emitterade formler bär med sig upplöst information om externa referenser och definierade namn

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;

Inuti WriteCommon är skrivaren ett ogenomskinligt handtag: anropa inte dess primitiva metoder — BeginContainer / EndContainer ramar in en taggad behållare och WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideString och WriteBytes kodar var sin kanoniska primitiv, med Finish som förseglar strömmen och Finished som rapporterar fullbordan — skicka tillbaka den till emissionshjälpfunktionerna nedan så att varje producent emitterar identiska byte

Globala startpunkter

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 fyller en stilpost med de kanoniska standardvärdena innan enskilda fält redigeras; XLSBuiltinSemanticNumberFormat mappar ett inbyggt talformat-id (under 164) till dess formatsträng, vilket konsumenter behöver för att tolka emitterade stilar och avkodade strömmar

Modellvokabulär

Emissionshjälpfunktioner

Dessa globala funktioner skriver ett modellfragment i skrivaren som skickas till WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinition och XLSWriteSemanticFormulaCell (formelceller bär arraygränser och ett valfritt cachat resultat). XLSWriteSemanticWorkbookCommon öppnar arbetsboksbehållaren och anropar WriteCommon, som anpassade källor normalt anropar först

Se även

gränssnitt IXLSWorkbook · klass TXLSXWorkbook · Metoden CreateReadOnlyView