Metodi SaveSemanticSnapshot e ComputeSemanticHash

Trasmette in streaming una rappresentazione canonica con versione della semantica del workbook o calcola il SHA-256 di esattamente quei byte

Sintassi

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;

I metodi sono esposti da IXLSWorkbook e TXLSWorkbook classici in lxHandlee da TXLSXWorkbook in lxHandleX

I tipi di profilo e di opzioni sono dichiarati in lxSemanticSnapshot e sono visibili attraverso entrambe le unità del workbook

Profili

Opzioni

The option set has type TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOptionGli overload senza parametri usano xlsspContent con un insieme di opzioni vuoto

Regole di streaming e di identità

• SaveSemanticSnapshot scrive alla posizione corrente del flusso di destinazione e non sposta, non possiede e non libera il flusso
• Un errore di scrittura a valle può lasciare un prefisso nella destinazione, quindi i chiamanti che richiedono una pubblicazione atomica devono scrivere su una destinazione temporanea prima di sostituire la destinazione finale
• ComputeSemanticHash restituisce 64 caratteri esadecimali minuscoli ed esegue l'hashing in modo incrementale senza allocare un buffer completo per l'istantanea
• L'istantanea è un protocollo semantico HotXLS, non un documento XLS, XLSX, ODS, CSV o PDF
• Confrontare istantanee o hash solo quando versione del protocollo, profilo e insieme di opzioni coincidono
• L'operazione non salva, non ricalcola, non aggiorna i collegamenti, non accede a risorse esterne e non modifica le cache del workbook

Funzionalità moderne delle celle

TXLSSemanticCellStyle.CellControlKind ha tipo TXLSSemanticCellControlKind con xlssControlNone, xlssControlUnknown e xlssControlCheckbox; CellControlDefaultState ha tipo TXLSSemanticCheckboxDefaultState con xlssCheckboxUnchecked, xlssCheckboxChecked e xlssCheckboxBlank

Le letture degli stili XLSX risolvono i controlli diretti ed ereditati senza creare celle; la serializzazione canonica degli stili rifiuta xlssControlUnknown invece di trattare un property bag sconosciuto come una cella ordinaria

Gli snapshot e gli hash includono rettangoli di controllo effettivi normalizzati, fondendo regioni adiacenti uguali senza espandere colonne intere in celle; gli overlay di stile non predefiniti non correlati conservano il loro confine esistente di normalizzazione non supportata

TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) restituisce voci scollegate chiavate per indirizzo di cella, inclusi i byte esatti codificati PNG o JPEG, il content type, il testo alternativo e i metadati decorativi; le quote coprono i byte canonici e le voci immagine, e i payload oversized vengono rifiutati prima della copia

Il confronto dei workbook include queste definizioni di immagini quando è selezionato lcoDrawings, mentre lcoCellStyles e lcoBlankStyleRegions includono i formati Checkbox effettivi; soli errori di fallback corrispondenti non rendono uguali immagini distinte

I grafi di immagini rich-value sconosciuti generano EXLSSemanticSnapshot durante il confronto delle funzionalità selezionate o la traversata dello snapshot; queste operazioni trattengono il lease di lettura del workbook e non calcolano le celle esaminate

Concorrenza ed errori

Entrambi i metodi trattengono un lease di lettura del workbook per l'intera traversata

Una mutazione pubblica concorrente fallisce prima di modificare lo stato del workbook con EXLSWorkbookWriteGuardUnavailable, mentre un cambio di generazione rilevato o una struttura semantica ambigua non supportata genera EXLSSemanticSnapshot

Esempio 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;

Esempio C++Builder

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

WideString hash = workbook->ComputeSemanticHash();

Riferimento del modello snapshot

Il motore di snapshot non è legato agli oggetti della cartella di lavoro: tutto quanto segue è dichiarato in lxSemanticSnapshot, e i metodi della cartella di lavoro sono sottili wrapper sugli stessi punti di ingresso globali

Interfacce di estensione

Implementare IXLSSemanticWorkbookSource per emettere o calcolare l'hash di uno snapshot di qualsiasi sorgente, e facoltativamente IXLSSemanticFormulaResolver così le formule emesse portano le informazioni risolte su riferimenti esterni e nomi definiti

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 WriteCommon il writer è un handle opaco: non chiamare i suoi metodi primitivi — BeginContainer / EndContainer incorniciano un container taggato e WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideStringe WriteBytes codificano ciascuna una primitiva canonica, con Finish che sigilla lo stream e Finished che segnala il completamento — passate l'handle ai helper di emissione qui sotto, così ogni produttore emette byte identici

Globali di punto di ingresso

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 riempie un record di stile con i valori predefiniti canonici prima che i singoli campi vengano modificati; XLSBuiltinSemanticNumberFormat mappa un id di formato numerico builtin (sotto 164) alla sua stringa di formato, che i consumatori devono conoscere per interpretare gli stili emessi e gli stream decodificati

Vocabolario del modello

Helper di emissione

Queste globali scrivono un frammento del modello nel writer passato a WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinitione XLSWriteSemanticFormulaCell (le celle formula trasportano i limiti dell'array e un risultato opzionale in cache). XLSWriteSemanticWorkbookCommon apre il container della cartella di lavoro e invoca WriteCommon, che le sorgenti personalizzate di norma chiamano per prime

Vedere anche

Interfaccia IXLSWorkbook · Classe TXLSXWorkbook · Metodo CreateReadOnlyView