الأسلوبان 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;

تكشف عن الأسلوبين واجهتا Classic‏ IXLSWorkbook وTXLSWorkbook في lxHandle، وTXLSXWorkbook في lxHandleX

يُعرَّف نوعا ملف التعريف والخيارات في lxSemanticSnapshot ويظهر كلاهما من خلال وحدتي المصنف

ملفات التعريف

الخيارات

نوع مجموعة الخيارات هو TXLSSemanticSnapshotOptions = set of TXLSSemanticSnapshotOption. تستخدم الأحمال الزائدة بلا معاملات القيمة xlsspContent مع مجموعة خيارات فارغة

قواعد التدفق والهوية

• يكتب SaveSemanticSnapshot عند الموضع الحالي للتدفق الهدف ولا ينفذ أي بحث ولا يتملك التدفق ولا يحرره
• قد يترك فشل الكتابة في المصب بادئة في الهدف، لذا على المتصلين الذين يشترطون نشرًا ذرّيًا الكتابة إلى هدف مؤقت قبل استبدال الوجهة
• يعيد ComputeSemanticHash 64 حرفًا سداسيًا عشريًا صغيرًا ويحسب قيمة التجزئة تزايديًا دون تخصيص مخزن مؤقت كامل للقطة
• اللقطة بروتوكول دلالي من HotXLS، وليست مستند XLS أو XLSX أو ODS أو CSV أو PDF
• قارن اللقطات أو قيم التجزئة فقط عندما تتطابق إصدار البروتوكول وملف التعريف ومجموعة الخيارات
• لا تحفظ العملية ولا تعيد الحساب ولا تُحدّث الارتباطات ولا تصل إلى موارد خارجية ولا تغيّر ذاكرات المصنف المؤقتة

ميزات الخلايا الحديثة

‏TXLSSemanticCellStyle.CellControlKind نوعها TXLSSemanticCellControlKind وتضم xlssControlNone وxlssControlUnknown وxlssControlCheckbox؛ وCellControlDefaultState نوعها TXLSSemanticCheckboxDefaultState وتضم xlssCheckboxUnchecked وxlssCheckboxChecked وxlssCheckboxBlank

قراءات أنماط XLSX تحل عناصر التحكم المباشرة والموروثة دون إنشاء خلايا؛ وتسلسل الأنماط القياسي يرفض xlssControlUnknown بدلًا من معاملة حزمة خصائص مجهولة كخلية عادية

اللقطات وقيم التجزئة تشمل مستطيلات التحكم الفعلية بعد التطبيع، وتدمج المناطق المتجاورة المتساوية دون توسيع أعمدة كاملة إلى خلايا؛ وتراكبات الأنماط غير الافتراضية غير ذات الصلة تحتفظ بحدّ التطبيع غير المدعوم الحالي

‏TXLSXWorkbook.ReadSemanticFeatures(xlsxSemanticCellImages, Sheet, AMaxBytes, AMaxItems) تعيد إدخالات منفصلة مفهرسة بعنوان الخلية، تشمل بايتات PNG أو JPEG المرمَّزة بدقة ونوع المحتوى والنص البديل وبيانات الزخرفة الوصفية؛ الحصص تغطي البايتات القياسية وإدخالات الصور، وتُرفض الحمولات الزائدة عن الحد قبل النسخ

مقارنة المصنفات تشمل تعريفات الصور هذه عند اختيار lcoDrawings، بينما يضم lcoCellStyles وlcoBlankStyleRegions تنسيقات Checkbox الفعلية؛ أخطاء fallback المتطابقة وحدها لا تجعل صورتين مختلفتين متساويتين

رسومات 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;

داخل WriteCommon يكون الكاتب مقبضًا معتمًا: لا تستدعِ أساليبه الأولية — تؤطر BeginContainer / EndContainer حاوية موسومة بوسم، وتشفر WriteNull وWriteBoolean وWriteUInt32 وWriteUInt64 وWriteInt32 وWriteInt64 وWriteBinary64 وWriteWideString وWriteBytes كلًّا من البدائيات القياسية، مع ختم 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 معرف تنسيق أرقام مدمجًا (أقل من 164) بسلسلة تنسيقه، وهو ما يحتاجه المستهلكون لتفسير الأنماط المكتوبة والتدفقات المفكوكة

مفردات النموذج

أدوات الإصدار المساعدة

تكتب هذه الدوال العامة جزء نموذج واحدًا في الكاتب الممرَّر إلى WriteCommon: ‏XLSWriteSemanticLiteralCell وXLSWriteSemanticCellStyle وXLSWriteSemanticColor وXLSWriteSemanticRanges وXLSWriteSemanticMerge وXLSWriteSemanticAxisEntry وXLSWriteSemanticFormulaTree وXLSWriteSemanticFormulaDefinition وXLSWriteSemanticFormulaCell (تحمل خلايا الصيغ حدود المصفوفة ونتيجة مخزنة اختيارية). ويفتح XLSWriteSemanticWorkbookCommon حاوية المصنف ويستدعي WriteCommon، التي تستدعيها المصادر المخصصة عادةً أولًا

انظر أيضًا

واجهة IXLSWorkbook · الفئة TXLSXWorkbook · الأسلوب CreateReadOnlyView