مراجع المصنفات الخارجية

نظرة عامة

غالبًا ما تستمد نماذج جداول البيانات بياناتها من مصنفات ثانوية باستخدام صيغ المراجع المتقاطعة؛ ويدعم HotXLS تحليل وكتابة والحفاظ على مراجع المصنفات الخارجية في مستندات BIFF8 (XLS الكلاسيكي) وOpenXML (XLSX) على حدٍّ سواء

مساحة عمل المصنفات الحية

TXLSWorkbookWorkspace في الوحدة lxWorkbookWorkspace هو نواة الهوية والتسجيل المشتركة للمصنفات الخارجية الحية؛ ويكشف كل من TXLSWorkbook وTXLSXWorkbook عن CreateWorkspaceWorkbook ويمتلك ExternalWorkspace تعتمدها مُقيّمات الصيغ لديهما، بينما يبلّغ مصنف ODS المفتوح عبر TXLSXWorkbook عن نوع محرك OpenDocument عبر المحوّل نفسه

var
  Host, Target: TXLSXWorkbook;
begin
  Host.ExternalWorkspace.Add(
    '..\Data\Target.xlsx',
    '..\Data\Target.xlsx',
    'C:\Models\Host.xlsx',
    Target.CreateWorkspaceWorkbook);

  // The compatibility facade maps an unambiguous name to the
  // relationship target already stored in Host.ExternalLinks
  Host.RegisterExternalWorkbook('Target.xlsx', Target);

  // The matching call revokes a facade-level registration
  Host.UnregisterExternalWorkbook('Target.xlsx');
end;

تستخدم المصنفات الكلاسيكية أساليب التوافقية نفسها مع أهداف من نوع TXLSWorkbook؛ ولا يدير RegisterExternalWorkbook وUnregisterExternalWorkbook سوى تعيين الأسماء على مستوى الـ facade، بينما يبطل ExternalWorkspace.Remove وClear تسجيلات مساحة العمل نفسها. ويضيف المستدعون عبر المحركات المختلفة أي محوّل من Classic أو XLSX أو ODS مباشرة إلى ExternalWorkspace

• توحيد الهوية معجمي وغير حساس لحالة الأحرف، ويحفظ المسارات والامتدادات، ويحل الأهداف النسبية وفق هوية المصدر المالك، ويطوي مقاطع النقاط، ومن دون أي وصول إلى نظام الملفات أو الشبكة
• تُحل الهويات المطابقة تمامًا والأسماء البديلة الصريحة أولًا؛ ولا ينجح البحث باسم الملف الأساسي وحده إلا عندما يطابق تسجيل واحد متصل بالضبط، وإلا أعاد Resolve القيمة xlswrsConflict
• يرفض Add التعارضات في المفتاح المطابق تمامًا وفي الاسم البديل وفي تكرار المصنف؛ ويمكن أن تتعايش المسارات الكاملة المختلفة والامتدادات المختلفة
• يبطل Remove وClear التسجيلات، بينما يؤدي تدمير هدف من نوع Classic أو XLSX مباشرةً إلى فصل محوّله والانتظار حتى ينتهي القرّاء النشطون قبل تحرير النموذج
• تُحل أوراق العمل الخارجية بالاسم المعلن أولًا قبل الرجوع إلى الموضع ذي الأساس واحد، فلا يلزم أن يطابق ترتيب أوراق المصنف الهدف دليل الروابط في المصدر
• يقرأ مُقيّم الصيغ المصنف الحي المحلول أولًا ثم يرتد إلى الذاكرة المؤقتة المنمَّطة في الملف المضيف؛ وتفك مصنفات Classic XLS الترميز للقيم XCT وCRN المتناثرة، بينما تستخدم مضيفات XLSX ذاكرة الروابط الخارجية التي يحملها نموذج الحزمة أصلًا
• يشكل OnLoadWorkbook طلبًا اختياريًا مضبوطًا للمورد؛ وقيمته الافتراضية nil، لذا يبقي إعادة الحساب بلا أي وصول إلى نظام الملفات أو الشبكة ما لم يوفر كود التطبيق تلك السياسة صراحةً
• لا يستدعى المحمّل لكل هوية موحدة أكثر من مرة واحدة حتى استدعاء ResetLoadAttempts؛ وتتشارك الطلبات العليا المتزامنة النتيجة الجارية، بما في ذلك نتائج عدم الوجود والأخطاء المنمَّطة، بدلًا من فتح المورد نفسه مرارًا
• القيمة الافتراضية لـ MaxLoadDepth هي 16 ولـ MaxWorkbookCount هي 64؛ وتعيد إعادة الدخول بالهوية نفسها، والتبعيات المتداخلة على هوية قيد التنفيذ أصلًا، واستنفاد العمق، واستنفاد عدد المصنفات، تشخيصات منمَّطة من دون حجب داخل دورة تحميل
• تبقى IRIات المصادر الخارجية في ODF هويات معجمية كاملة، بما في ذلك مخططات URI والمحارف المقتبسة، لكنها لا تسمح قط بوصول ضمني إلى الملفات أو الشبكة
• يبقى تعارض الهويات #REF! حتى لا تخفي البيانات القديمة المخزنة مؤقتًا توجيهًا غامضًا؛ ولا تكون الخلية الغائبة في الذاكرة المؤقتة قيمة فارغة إلا إذا أعلن الملف عن ذاكرة مؤقتة صالحة لتلك الورقة

يجري Resolve البحث في التسجيلات ثم التحميل المضبوط الاختياري؛ ونتيجته من نوع TXLSWorkspaceResolveStatus (xlswrsResolved أو xlswrsNotFound أو xlswrsConflict أو xlswrsDisconnected أو xlswrsLoadNotFound أو xlswrsLoadLimit أو xlswrsLoadLoop أو xlswrsLoadError)، كما يعيد ResolveWithLoader كذلك TXLSWorkspaceLoadDiagnostic يقترن فيه TXLSWorkspaceLoadDiagnosticCode بـ TXLSWorkspaceLoadResponseStatus (xlswlrsNotFound وxlswlrsResolved وxlswlrsError) للتفريق بين نتائج عدم الوجود وخطأ المحمّل والنتيجة المنفصلة وحد العمق أو حد عدد المصنفات وإعادة دخول الهوية والتبعية المتزامنة وتعارض التسجيل. ويستقبل رد الندرة الخاص بالمحمّل TXLSWorkspaceLoadRequest (الهوية والعمق وعدد المسجل والحدود) ويجيب بـ TXLSWorkspaceLoadResponse

يبلّغ Recalculate عن TXLSWorkspaceRecalcStatus، ومعه اختياريًا تفصيل TXLSWorkspaceRecalcResult، ويسجل المُقيّم أصل كل خلية بوصفه TXLSWorkspaceRuntimeLookup (xlswrlInactive أو xlswrlResolved أو xlswrlFallbackCache أو xlswrlError) حتى يتميّز التشخيص بين القراءة الحية والارتداد إلى الذاكرة المؤقتة

يكشف المحوّل IXLSWorkspaceWorkbook عن EngineKind (من نوع TXLSWorkspaceEngineKind: xlsweClassic أو xlsweOpenXml أو xlsweOpenDocument) وSourceIdentity وInstanceIdentity وGeneration، ويختبر الحيوية عبر IsConnected، ويقرأ خلية واحدة عبر TryGetCellValue (معيدًا TXLSWorkspaceCellStatus منمَّطًا: قيمة أو غياب أو مرجع غير صالح أو انفصال أو خطأ، مع علم الخروج من نطاق الاستخدام)، ويحدّث النموذج عبر Recalculate، وينفصل عن نموذج المصنف عبر Disconnect

يضيف السجل AddAlias لأسماء إضافية مرتبطة بهوية مسجلة واحدة، وTryResolve بوصفه نسخة البحث الخالية من الاستثناءات، وBaseNameMatchCount لاستطلاع عدد التسجيلات المتصلة التي تتشارك الاسم الأساسي قبل اختيار هدف غير غامض

مخطط التبعيات عبر المصنفات

يلتقط BuildDependencyGraph لقطة عن كل محوّل مصنف مسجل ويستخرج عُقد الصيغ من نماذج Classic XLS وXLSX وODS في TXLSWorkspaceDepGraph واحد؛ ويعيد الأسلوب False بلا مخطط جزئي إذا عجز أي محوّل مسجل عن توفير بيانات التبعيات الوصفية

• يحفظ كل عقدة صيغة هوية المصنف القانونية واسم ورقة العمل وموضعها ذا الأساس واحد، وموضع الخلية ذا الأساس صفر، ومستطيل مخرجات الصفيفة، وحالة التقلب، وحالة المراجع غير المحلولة
• تحفظ مراجع الخلايا والنطاقات المستطيلة هويات المصنف الهدف وورقة العمل القانونية؛ وتبقى مراجع الأعمدة الكاملة والصفوف الكاملة وورقة العمل كاملة فترة واحدة بدلًا من تمددها إلى ملايين الخلايا
• تبقى الأسماء المعرفة المحلية قابلة للاستعلام بوصفها تبعيات رمزية، وتمتد أيضًا إلى تبعيات خلاياها أو نطاقاتها الملموسة عندما يمكن حل تعريفها استاتيكيًا
• تحفظ الأسماء المعرفة الخارجية خانة الارتباط الخارجي والاسم المعلن ونطاق ورقة العمل الاختياري والهوية القانونية للهدف، من دون معاملة بيانات DDE أو OLE أو دالات المستخدم الوصفية كأسماء مصنفات
• يستخدم FindDependentsOfCell وبناء حواف المخطط أشجار فترات الصفوف مع تقليم النهايات القصوى؛ وتكشف LastRangeCandidateChecks وEdgeCandidateChecks عن عدد عمليات فحص المستطيلات الدقيقة للتحقق من الأداء
• يعمل استخراج الصيغ تحت عقود قراءة المصنف ويكتفي بمسح كائنات الصيغ المجسدة، فتبقى مخازن القيم المضغوطة مضغوطة ولا يغيّر إنشاء المخطط أطوار توليد المصنف

إعادة الحساب المجدولة

يحتفظ Recalculate بالمخطط المشترك ويعيد بناءه فقط عندما تتغير تسجيلات مساحة العمل أو طور تبعيات صيغ أحد المصنفات؛ وتبذر أطوار القيم مسارًا جديدًا للقيم المتسخة، وتنتقل التساخ عبر حواف التبعيات عبر المصنفات

var
  RecalcInfo: TXLSWorkspaceRecalcResult;
  Status: TXLSWorkspaceRecalcStatus;
begin
  Status := Workspace.Recalculate(RecalcInfo);
  if Status <> xlswrcOk then
    HandleWorkspaceCalculation(Status, RecalcInfo);
end;

• تُحسب المكونات شديدة الترابط على خلايا الصيغ، فيجوز للمصنفات أن تترابط في الاتجاهين مع بقائها بلا دورات ما دامت مسارات تبعيات الخلايا لديها لا تكوّن حلقة
• يُبطل أعضاء الدورات الحقيقيون والأحفاد المتسخون المحجوبون بدورة ما ويُستبعدون من الترتيب الطوبولوجي، مما يمنع تقديم قيم مخزنة قديمة بوصفها نتائج ناجحة
• تفرض المراجع المتقلبة أو غير المحلولة استاتيكيًا سلوك التساخ المحافظ المطلوب للصحة، بينما تعيد المخططات المستقرة استخدام عمل التبعيات السابق
• تستخدم القراءات الخارجية داخل المسار ذاكرة مؤقتة دقيقة بمستوى نسخة المصنف وورقة العمل والصف والعمود؛ وتبطل الصيغة المجدولة نطاق مخرجاتها قبل التقييم ليلاحظ التابعون اللاحقون القيمة الجديدة
• لا يمنح المخزن المحلي للمسار أي سلطة على الموارد؛ وتظل المصنفات المسجلة والمحمّل الاختياري المضبوط من المستدعي المصدرين الوحيدين للحل الحي، يليهما الملفات المنمَّطة للذاكرات المؤقتة ثم #REF!
• يكشف TXLSWorkspaceRecalcResult عن ما إذا أُعيد بناء المخطط، إضافة إلى عدّادات القيم المتسخة والمقيّمة والمبطلة وحالات الدورات والمحجوبة وإصابات الذاكرة المؤقتة وخطئها
• يميز الحالة بين النجاح والمحولات غير المدعومة والمصنفات المنفصلة والمراجع الدائرية وأخطاء الحساب وتغيير مساحة العمل أثناء المسار
• تُتسلسل استدعاءات Recalculate على مساحة العمل نفسها، فلا تعدّل جلستان حسابيان أبدًا المخطط المشترك أو ذاكرات المصنف المؤقتة بالتوازي
• يجوز أن يعمل Remove أو Clear أثناء نشاط مسار؛ إذ يحتفظ المسار بلقطات آمنة للمحولات ويعيد xlswrcWorkspaceChanged بدلًا من إلغاء الإشارة إلى تسجيل أُزيل
• يؤدي تدمير مساحة العمل إلى انتظار انتهاء مسارها النشط، بينما يؤدي تدمير مصنف مسجل إلى فصل محوّله وإخفاق الحلول اللاحقة بأمان
• تبقى إخفاقات المحمّل ونتائج عدم الوجود مخزنة مرة واحدة لكل هوية موحدة حتى ResetLoadAttempts، ويحتفظ الحساب الفاشل بالحالة المتسخة محليًا لإعادة المحاولة الصريحة
• يجعل المخطط المحتفظ به المسار التالي غير المتغير متناسبًا مع عدد المصنفات المسجلة لا مع عدد الصيغ؛ ويحافظ تحليل المكونات غير التكراري وحواف النطاقات المضغوطة على بقاء النماذج العميقة والواسعة ضمن حدود بيانات الصيغ المجسدة

فصل الأسماء المعرفة الخارجية

يوفر ConvertExternalDefinedNamesToRefErrors العملية العامة نفسها على TXLSWorkbook وTXLSXWorkbook؛ ويعيد عدد التعريفات ذات النطاق على مستوى المصنف أو ورقة العمل التي استُبدلت بـ #REF! الأصلية

var
  Converted: Integer;
begin
  Converted := Workbook.ConvertExternalDefinedNamesToRefErrors;
  // External-link parts and ordinary cell formulas remain intact
end;

• يعتمد اختيار Classic XLS على رموز مراجع BIFF المترجمة وهوية مصنف الدعم في XTI، فتبقى المراجع ثلاثية الأبعاد داخل المصنف نفسه وتدفقات الرموز غير المؤكدة دون تغيير
• يعتمد اختيار XLSX على خانات المصنفات الرقمية الواعية بالبنية بترتيب مستند العلاقات، ولا يقبل إلا أجزاء روابط المصنفات الخارجية، مستبعدًا DDE وOLE والخانات غير المحلولة ومراجع الجداول والنص بين الأقواس داخل السلاسل
• تُجهَّز جميع الاستبدالات قبل أول تعديل وتُرسَّز كعملية كتابة واحدة؛ والاستدعاء الثاني ذو أثر مكرر (idempotent)
• يبقى نص الاسم ونطاق المصنف أو ورقة العمل والرؤية والتعليقات وأعلام الماكرو والأسماء المدمجة وسمات XLSX غير المعروفة ودليل الروابط الخارجية متاحة بعد التحويل وعبر جولة الذهاب والإياب (Roundtrip)
• تبقى التعريفات المشوهة وغير المدعومة حافظة للبايتات أو النص قدر الإمكان وتضيف تشخيصات xlsDiagnosticDefinedNameConversionSkipped بدلًا من التخمين
• يعاد حساب الصيغ التابعة إلى قيمة خطأ Excel المقابلة، بينما تبقى النتيجة المخزنة الصالحة لصيغة خارجية مباشرة عادية متاحة إذا انفصل مصنفها الحي لاحقًا
• العملية خاصة بـ Excel ولا تعيد تفسير دلالات صيغة الاسم في OpenDocument

المراجع الخارجية لـ XLS الكلاسيكي

في مصنفات XLS الكلاسيكية، تُخزَّن الروابط الخارجية في كتلة الدليل العام باستخدام سجلات EXTERNALBOOK وEXTERNNAME؛ ويحافظ HotXLS على هذه الأدلة أثناء دورات قراءة/كتابة الملفات، مما يضمن بقاء مراجع النطاقات البعيدة عبر حلقات التعديل

العلاقات الخارجية لـ XLSX

بالنسبة لمصنفات OOXML، تُدار تعيينات الروابط الخارجية عبر أجزاء العلاقات؛ راجع تفاصيل الواجهات الداعمة أدناه

• الفئة TXLSXExternalLinks — واجهة لسرد وتحديث الروابط الخارجية لجدول البيانات
• الواجهة IXLSWorkbook — خصائص المصنف عالية المستوى
• الخاصية IXLSRange.Formula — قراءة وكتابة الصيغ عبر المصنفات