Metody SaveSemanticSnapshot i ComputeSemanticHash

Zapisuje w strumieniu wersjonowaną kanoniczną reprezentację semantyki skoroszytu albo oblicza SHA-256 dokładnie tych bajtów

Składnia

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;

Metody są udostępniane przez klasyczne IXLSWorkbook i TXLSWorkbook w lxHandle oraz przez TXLSXWorkbook w lxHandleX

Typy profilu i opcji są zadeklarowane w lxSemanticSnapshot i widoczne przez obie jednostki skoroszytu

Profile

Opcje

Zestaw opcji ma typ TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOption. Przeciążenia bez parametrów używają xlsspContent z pustym zestawem opcji

Zasady strumieniowania i tożsamości

• SaveSemanticSnapshot zapisuje w bieżącej pozycji strumienia docelowego i nie wykonuje przewijania, nie przejmuje własności strumienia ani go nie zwalnia
• Błąd zapisu po stronie podrzędnej może pozostawić początkowy fragment w obiekcie docelowym, więc obiekty wywołujące wymagające niepodzielnej publikacji powinny najpierw zapisywać do obiektu tymczasowego, a dopiero potem zastępować miejsce docelowe
• ComputeSemanticHash zwraca 64 małe znaki szesnastkowe i oblicza skrót przyrostowo, bez przydzielania pełnego bufora migawki
• Migawka to semantyczny protokół HotXLS, a nie dokument XLS, XLSX, ODS, CSV ani PDF
• Porównuj migawki lub skróty tylko wtedy, gdy zgadzają się wersja protokołu, profil i zestaw opcji
• Operacja nie zapisuje, nie przelicza ponownie, nie odświeża łączy, nie uzyskuje dostępu do zasobów zewnętrznych i nie modyfikuje pamięci podręcznych skoroszytu

Nowoczesne funkcje komórek

TXLSSemanticCellStyle.CellControlKind ma typ TXLSSemanticCellControlKind z wartościami xlssControlNone, xlssControlUnknowni xlssControlCheckbox; CellControlDefaultState ma typ TXLSSemanticCheckboxDefaultState z wartościami xlssCheckboxUnchecked, xlssCheckboxCheckedi xlssCheckboxBlank

Odczyty stylów XLSX rozwiązywają kontrolki bezpośrednie i dziedziczone bez tworzenia komórek; kanoniczna serializacja stylów odrzuca xlssControlUnknown zamiast traktować nieznany worek właściwości jak zwykłą komórkę

Migawki i skróty obejmują znormalizowane efektywne prostokąty kontrolek, scalając przyległe równe regiony bez rozszerzania całych kolumn na komórki; niepowiązane niebędące domyślnymi nakładki stylów zachowują istniejącą granicę nieobsługiwanej normalizacji

TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) zwraca odłączone wpisy kluczowane adresem komórki, włącznie z dokładnymi zakodowanymi bajtami PNG lub JPEG, typem zawartości, tekstem alternatywnym i metadanymi decorative; kwoty obejmują kanoniczne bajty i wpisy obrazów, a zbyt duże ładunki są odrzucane przed kopiowaniem

Porównywanie skoroszytów obejmuje te definicje obrazów, gdy wybrano lcoDrawings, podczas gdy lcoCellStylesi lcoBlankStyleRegions obejmują efektywne formaty Checkbox; same zgodne błędy fallback nie czynią odrębnych obrazów równymi

Nieznane grafy obrazów rich-value zgłaszają EXLSSemanticSnapshot podczas porównywania wybranych funkcji albo przechodzenia migawki; te operacje zachowują dzierżawę odczytu skoroszytu i nie obliczają badanych komórek

Współbieżność i błędy

Obie metody utrzymują dzierżawę odczytu skoroszytu przez cały czas przechodzenia

Równoczesna publiczna mutacja kończy się niepowodzeniem ze EXLSWorkbookWriteGuardUnavailable przed zmianą stanu skoroszytu, podczas gdy wykryta zmiana generacji lub nieobsługiwana niejednoznaczna struktura semantyczna zgłasza EXLSSemanticSnapshot

Przykład dla 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;

Przykład dla C++Builder

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

WideString hash = workbook->ComputeSemanticHash();

Dokumentacja modelu migawki

Silnik migawki nie jest związany z obiektami skoroszytu: wszystko poniżej jest zadeklarowane w lxSemanticSnapshot, a metody skoroszytu są cienkimi opakowaniami tych samych globalnych punktów wejścia

Interfejsy rozszerzeń

Zaimplementuj IXLSSemanticWorkbookSource, aby emitować lub haszować migawkę dowolnego źródła, i opcjonalnie IXLSSemanticFormulaResolver, aby emitowane formuły nieśli rozwiązane informacje o odwołaniach zewnętrznych i nazwach zdefiniowanych

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;

Wewnątrz WriteCommon writer jest nieprzejrzystym uchwytem: nie wywołuj jego metod pierwotnych — BeginContainer / EndContainer wyznaczają ramy kontenera z tagiem, a WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideString i WriteBytes kodują po jednej kanonicznej wartości pierwotnej każda; Finish uszczelnia strumień, a Finished raportuje zakończenie — przekazuj go z powrotem do pomocników emisji poniżej, dzięki czemu każdy producent emituje identyczne bajty

Globalne punkty wejścia

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 wypełnia rekord stylu kanonicznymi wartościami domyślnymi przed edycją poszczególnych pól; XLSBuiltinSemanticNumberFormat mapuje identyfikator wbudowanego formatu liczb (poniżej 164) na jego ciąg formatu, którego konsumenci potrzebują do interpretacji emitowanych stylów i zdekodowanych strumieni

Słownik modelu

Pomocnicy emisji

Te globalne funkcje zapisują jeden fragment modelu do writera przekazanego do WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinition oraz XLSWriteSemanticFormulaCell (komórki formuł niosą granice tablicy i opcjonalny wynik z pamięci podręcznej). XLSWriteSemanticWorkbookCommon otwiera kontener skoroszytu i wywołuje WriteCommon, co niestandardowe źródła normalnie wywołują jako pierwsze

Zobacz także

Interfejs IXLSWorkbook · Klasa TXLSXWorkbook · Metoda CreateReadOnlyView