SaveSemanticSnapshot メソッドと ComputeSemanticHash メソッド

バージョン付きのワークブックセマンティクスの正準表現をストリーミングするか、まさにそのバイトの SHA-256 を計算します

構文

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;

これらのメソッドは、lxHandle のクラシック IXLSWorkbook と TXLSWorkbook、および lxHandleX の TXLSXWorkbook によって公開されます

プロファイル型とオプション型は lxSemanticSnapshot で宣言され、両方のワークブックユニットを通じて参照できます

プロファイル

値	意味
`xlsspContent`	通常のセマンティクス同一性チェックに適した正規のワークブックコンテンツ
`xlsspSecurityComplete`	コンテンツに加えて、サポートされている不透明なセキュリティ状態と保存状態。これらは通常のコンテンツ同一性から意図的に除外されています

オプション

値	含まれる状態
`xlssoIncludeViewerState`	選択、アクティブビューの状態、およびサポートされているその他のビューアー向けの状態
`xlssoIncludeVolatileMetadata`	サポートされているタイムスタンプ、プロデューサーメタデータ、および意図的に揮発性となるその他のフィールド
`xlssoIncludeFormulaCachedResults`	保存された数式結果とサポートされている外部リンクキャッシュ。再計算や外部 I/O は行いません

オプションセットの型は TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOption です。パラメータなしのオーバーロードは、空のオプションセットで xlsspContent を使用します

ストリーミングと同一性の規則

SaveSemanticSnapshot はターゲットストリームの現在位置に書き込み、ストリームをシークせず、所有も解放もしません
下流の書き込み失敗によりターゲットの冒頭部分が書き込まれたまま残る可能性があるため、アトミックな公開が必要な呼び出し元は、最終的な宛先を置き換える前に一時的なターゲットに書き込む必要があります
ComputeSemanticHash は 64 文字の小文字の 16 進文字列を返し、スナップショット全体のバッファを割り当てることなく増分的にハッシュ計算します
スナップショットは HotXLS のセマンティックプロトコルであり、XLS、XLSX、ODS、CSV、PDF のドキュメントではありません
スナップショットやハッシュを比較するのは、プロトコルバージョン、プロファイル、オプションセットが一致する場合のみにしてください
この操作は、保存、再計算、リンクの更新、外部リソースへのアクセス、ワークブックキャッシュの変更を行いません

モダンなセル機能

TXLSSemanticCellStyle.CellControlKind は xlssControlNone、xlssControlUnknown、xlssControlCheckbox を持つ TXLSSemanticCellControlKind 型で、CellControlDefaultState は xlssCheckboxUnchecked、xlssCheckboxChecked、xlssCheckboxBlank を持つ TXLSSemanticCheckboxDefaultState 型です

XLSX のスタイル読み取りは、セルを作成せずに直接制御と継承された制御を解決します。正準スタイルシリアライズは、未知のプロパティバッグを通常のセルとして扱う代わりに xlssControlUnknown を拒否します

スナップショットとハッシュには正規化された実効制御矩形が含まれ、隣接する等価リージョンをマージしますが、列全体をセルに展開することはありません。無関係な既定外スタイルオーバーレイは、既存の正規化未対応境界をそのまま保ちます

TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) は、セルアドレスをキーとする独立したエントリを返します。内容は正確にエンコードされた PNG または JPEG バイト、コンテンツタイプ、代替テキスト、装飾メタデータです。クォータは正準バイトと画像エントリを対象とし、過大なペイロードはコピー前に拒否されます

ワークブック比較では、lcoDrawings を選択したときにこれらの画像定義が含まれ、lcoCellStyles と lcoBlankStyleRegions には実効 Checkbox 形式が含まれます。フォールバックエラーが一致するだけでは、異なる画像は等価になりません

未知のリッチ値画像グラフは、選択した機能の比較やスナップショット走査中に EXLSSemanticSnapshot を発生させます。これらの操作はワークブックの読み取りリースを保持し、検査対象のセルを計算しません

コンカレンシーとエラー

両方のメソッドは、トラバーサル全体にわたってワークブックの読み取りリースを保持します

同時発生する公開の変更は、ワークブックの状態を変更する前に EXLSWorkbookWriteGuardUnavailable で失敗します。一方、検出された世代の変更やサポートされていないあいまいなセマンティック構造は EXLSSemanticSnapshot を発生させます

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;

C++Builder の例

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

WideString hash = workbook->ComputeSemanticHash();

スナップショットモデルリファレンス

スナップショットエンジンはワークブックオブジェクトに結び付いていません。以下はすべて lxSemanticSnapshot で宣言されており、ワークブックのメソッドは同じグローバルエントリポイントの薄いラッパーです

拡張インターフェース

任意のソースのスナップショットを出力またはハッシュするには IXLSSemanticWorkbookSource を実装します。さらにオプションで IXLSSemanticFormulaResolver を実装すると、出力される数式が解決済みの外部参照と定義名の情報を持つようになります

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;

WriteCommon の内部でライターは不透明なハンドルです。プリミティブメソッドを直接呼び出さないでください。BeginContainer / EndContainer はタグ付きコンテナーを枠付けし、WriteNull、WriteBoolean、WriteUInt32、WriteUInt64、WriteInt32、WriteInt64、WriteBinary64、WriteWideString、WriteBytes はそれぞれ 1 つの正準プリミティブをエンコードし、Finish がストリームを封印、Finished が完了を報告します。すべてのプロデューサーが同一のバイトを出力できるよう、ハンドルは下記のエミッションヘルパーに渡してください

エントリポイントのグローバル関数

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 は、個々のフィールドを編集する前にスタイルレコードを正準な既定値で埋めます。XLSBuiltinSemanticNumberFormat は、組み込み数値書式 ID（164 未満）をその書式文字列にマップします。出力されたスタイルやデコードされたストリームを解釈するために、コンシューマーはこれを必要とします

モデル語彙

グループ	型
シート	`TXLSSemanticSheetKind`（ワークシート、マクロ、グラフ、VBA、不明）、`TXLSSemanticSheetVisibility`（表示、非表示、非常に隠す）、`TXLSSemanticDefinedNameScope`（ワークブックまたはワークシート）、`TXLSSemanticRange` / `TXLSSemanticRanges`（結合、条件付き書式、テーブルが使う矩形範囲）
セル	`TXLSSemanticCellKind`（空白、数値、日時、テキスト、真偽値、エラー、数式）
スタイル	`TXLSSemanticCellStyle`（完全な正準セルスタイル）、`TXLSSemanticColorKind`（なし、自動、システム、ARGB、テーマ、インデックス）とティントを伴う `TXLSSemanticColor`、`TXLSSemanticBorderEdge` / `TXLSSemanticBorderStyle`、`TXLSSemanticFillPattern`、`TXLSSemanticGradientKind` / `TXLSSemanticGradientStop` / `TXLSSemanticGradientStops`、`TXLSSemanticUnderline`、`TXLSSemanticFontVerticalAlign`
数式	`TXLSSemanticFormulaEncoding`（解析済みツリーか不透明テキストか）、`TXLSSemanticFormulaArrayKind`（なし、CSE、ダイナミック）、`TXLSSemanticFormulaNodeKind`、`TXLSSemanticFormulaRangeKind`、`TXLSSemanticFormulaLinkKind`（同一シート、内部、外部、アドイン、DDE、OLE、その他）、`TXLSSemanticFormulaNameKind`
描画とグラフ	`TXLSSemanticDrawingKind`（画像、テキストボックス、グラフ、グループ、フォームコントロール）、`TXLSSemanticDrawingAnchorMode`（移動とサイズ変更、移動のみ、絶対）、`TXLSSemanticImageFormat`、`TXLSSemanticChartFamily`

エミッションヘルパー

これらのグローバル関数は、WriteCommon に渡されたライターへ 1 つのモデルフラグメントを書き込みます。XLSWriteSemanticLiteralCell、XLSWriteSemanticCellStyle、XLSWriteSemanticColor、XLSWriteSemanticRanges、XLSWriteSemanticMerge、XLSWriteSemanticAxisEntry、XLSWriteSemanticFormulaTree、XLSWriteSemanticFormulaDefinition、XLSWriteSemanticFormulaCell（数式セルは配列の境界とオプションのキャッシュ結果を保持します）。XLSWriteSemanticWorkbookCommon はワークブックコンテナーを開いて WriteCommon を呼び出します。カスタムソースは通常、これを最初に呼び出します