Méthodes SaveSemanticSnapshot et ComputeSemanticHash

Diffuse une représentation canonique versionnée de la sémantique du classeur ou calcule le SHA-256 d'exactement ces octets

Syntaxe

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;

Les méthodes sont exposées par IXLSWorkbook et TXLSWorkbook classiques dans lxHandle, et par TXLSXWorkbook dans lxHandleX

Les types de profil et d'options sont déclarés dans lxSemanticSnapshot et sont visibles via les deux unités de classeur

Profils

Options

The option set has type TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOptionLes surcharges sans paramètre utilisent xlsspContent avec un jeu d'options vide

Règles de diffusion et d'identité

• SaveSemanticSnapshot écrit à la position courante du flux cible et ne repositionne pas, ne possède pas et ne libère pas le flux
• Un échec d'écriture en aval peut laisser un préfixe dans la cible ; les appelants qui exigent une publication atomique doivent donc écrire vers une cible temporaire avant de remplacer la destination
• ComputeSemanticHash renvoie 64 caractères hexadécimaux minuscules et hache de manière incrémentielle sans allouer un tampon d'instantané complet
• L'instantané est un protocole sémantique HotXLS, et non un document XLS, XLSX, ODS, CSV ou PDF
• Ne comparez des instantanés ou des hachages que si la version du protocole, le profil et le jeu d'options correspondent
• L'opération n'enregistre pas, ne recalcule pas, n'actualise pas les liens, n'accède à aucune ressource externe et ne mute pas les caches du classeur

Fonctionnalités modernes de cellules

TXLSSemanticCellStyle.CellControlKind a le type TXLSSemanticCellControlKind avec xlssControlNone, xlssControlUnknown et xlssControlCheckbox ; CellControlDefaultState a le type TXLSSemanticCheckboxDefaultState avec xlssCheckboxUnchecked, xlssCheckboxChecked et xlssCheckboxBlank

Les lectures de styles XLSX résolvent les contrôles directs et hérités sans créer de cellules ; la sérialisation canonique des styles rejette xlssControlUnknown au lieu de traiter un sac de propriétés inconnu comme une cellule ordinaire

Les instantanés et les hachages incluent les rectangles effectifs normalisés de contrôles, en fusionnant les régions adjacentes égales sans étendre les colonnes entières en cellules ; les superpositions de styles non par défaut sans rapport conservent leur limite existante de normalisation non prise en charge

TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) renvoie des entrées détachées indexées par adresse de cellule, y compris les octets PNG ou JPEG encodés exacts, le type de contenu, le texte alternatif et les métadonnées décoratives ; les quotas couvrent les octets canoniques et les entrées d'images, et les charges trop grandes sont rejetées avant copie

La comparaison de classeurs inclut ces définitions d'images quand lcoDrawings est sélectionné, tandis que lcoCellStyles et lcoBlankStyleRegions incluent les formats Checkbox effectifs ; des erreurs de repli identiques seules ne rendent pas des images distinctes égales

Les graphes d'images rich-value inconnus lèvent EXLSSemanticSnapshot lors d'une comparaison de fonctionnalités sélectionnée ou d'une traversée d'instantané ; ces opérations conservent le bail de lecture du classeur et ne calculent pas les cellules inspectées

Concurrence et erreurs

Les deux méthodes détiennent un bail de lecture du classeur pour toute la traversée

Une mutation publique concurrente échoue avant de modifier l'état du classeur avec EXLSWorkbookWriteGuardUnavailable, tandis qu'un changement de génération détecté ou une structure sémantique ambiguë non prise en charge lève EXLSSemanticSnapshot

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

Exemple C++Builder

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

WideString hash = workbook->ComputeSemanticHash();

Référence du modèle d'instantané

Le moteur d'instantanés n'est pas lié aux objets du classeur : tout ce qui suit est déclaré dans lxSemanticSnapshot, et les méthodes du classeur ne sont que de fines surcouches des mêmes points d'entrée globaux

Interfaces d'extension

Implémentez IXLSSemanticWorkbookSource pour diffuser ou hacher un instantané de n'importe quelle source, et optionnellement IXLSSemanticFormulaResolver afin que les formules diffusées transportent les informations résolues de références externes et de noms définis

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;

À l'intérieur de WriteCommon , le writer est un handle opaque : n'appelez pas ses méthodes primitives — BeginContainer / EndContainer encadrent un conteneur étiqueté et WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideStringet WriteBytes encodent chacun une primitive canonique, avec Finish qui scelle le flux et Finished qui signale l'achèvement — repassez-le aux fonctions d'aide de diffusion ci-dessous afin que chaque producteur émette des octets identiques

Globaux de point d'entrée

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 remplit un enregistrement de style avec les valeurs par défaut canoniques avant l'édition de champs individuels ; XLSBuiltinSemanticNumberFormat mappe un identifiant de format numérique intégré (inférieur à 164) vers sa chaîne de format, dont les consommateurs ont besoin pour interpréter les styles diffusés et les flux décodés

Vocabulaire du modèle

Fonctions d'aide de diffusion

Ces globaux écrivent un fragment de modèle dans le writer passé à WriteCommon: XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinitionet XLSWriteSemanticFormulaCell (les cellules de formule transportent les bornes de tableau et un résultat en cache optionnel). XLSWriteSemanticWorkbookCommon ouvre le conteneur du classeur et invoque WriteCommon, que les sources personnalisées appellent normalement en premier

Voir aussi

Interface IXLSWorkbook · Classe TXLSXWorkbook · Méthode CreateReadOnlyView