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;

이 메서드는 IXLSWorkbook 의 클래식 TXLSWorkbook 및 lxHandle과 TXLSXWorkbook 의 lxHandleX

프로필 및 옵션 형식은 lxSemanticSnapshot 에 선언되며 두 통합 문서 단위를 통해 모두 표시됩니다

프로필

옵션

매개 변수 없는 오버로드는 빈 옵션 집합으로 TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOption를 사용합니다 xlsspContent with an empty option set

스트리밍 및 동일성 규칙

• SaveSemanticSnapshot 은 대상 스트림의 현재 위치에 쓰며, 스트림을 탐색하거나 소유하거나 해제하지 않습니다
• 다운스트림 쓰기 실패 시 대상에 접두 부분이 남을 수 있으므로, 원자적 게시가 필요한 호출자는 대상을 대체하기 전에 임시 대상에 써야 합니다
• ComputeSemanticHash 는 소문자 16진수 64자를 반환하고, 전체 스냅숏 버퍼를 할당하지 않고 증분적으로 해시를 계산합니다
• 스냅숏은 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 바이트 그대로, 콘텐츠 타입, 대체 텍스트, 장식(decorative) 메타데이터를 담습니다. 할당량은 정식 바이트와 이미지 항목을 커버하고, 과대한 페이로드는 복사 전에 거부됩니다

통합 문서 비교는 lcoDrawings를 선택하면 이 이미지 정의를 포함하고, lcoCellStyles와 lcoBlankStyleRegions는 유효 Checkbox 형식을 포함합니다. 폴백 오류만 일치한다고 서로 다른 이미지가 같아지지는 않습니다

알 수 없는 rich-value 이미지 그래프는 선택된 기능 비교나 스냅숏 순회 중 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;

Inside WriteCommon 안에서 writer는 불투명한 핸들입니다. 기본 메서드를 직접 호출하지 말고 BeginContainer / EndContainer 는 태그가 붙은 컨테이너를 프레이밍하고, WriteNull, WriteBoolean, WriteUInt32, WriteUInt64, WriteInt32, WriteInt64, WriteBinary64, WriteWideString, WriteBytes 는 각각 하나의 정식(canonical) 프리미티브를 인코딩하며, Finish 가 스트림을 봉인하고 Finished 가 완료를 보고합니다. 아래의 방출(emission) 헬퍼에 이 핸들을 다시 넘겨 모든 생산자가 동일한 바이트를 내보내도록 하십시오

진입점 전역 함수

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 미만)를 서식 문자열로 매핑하며, 소비자가 내보내진 스타일과 디코딩된 스트림을 해석하려면 이 매핑이 필요합니다

모델 어휘

방출 헬퍼

이 전역 함수들은 WriteCommon에 전달된 writer에 모델 조각 하나를 기록합니다. XLSWriteSemanticLiteralCell, XLSWriteSemanticCellStyle, XLSWriteSemanticColor, XLSWriteSemanticRanges, XLSWriteSemanticMerge, XLSWriteSemanticAxisEntry, XLSWriteSemanticFormulaTree, XLSWriteSemanticFormulaDefinition, XLSWriteSemanticFormulaCell (수식 셀은 배열 경계와 선택적 캐시 결과를 함께 전달합니다). XLSWriteSemanticWorkbookCommon 은 통합 문서 컨테이너를 열고 WriteCommon을 호출하며, 사용자 지정 소스는 보통 이것을 가장 먼저 호출합니다

참고 항목

IXLSWorkbook 인터페이스 · TXLSXWorkbook 클래스 · CreateReadOnlyView 메서드