وثائق HotXLS

دعم Free Pascal وLazarus

يدعم HotXLS الإصدار Free Pascal 3.2.2 مع Lazarus/LCL على Windows بمعماريتَي Win32 وWin64، بما يشمل واجهات برمجة تطبيقات مصنفات XLS/XLSX والصيغ والتنسيق والبث المباشر ومكوّنَي التصدير TDataToXLS وTGridToXLS وأدوات العرض المساعدة

نواة المصنف الأصلية على Linux و macOS

راجع تخزين الملفات المركبة لمعرفة واجهات برمجة المجلدات ذات النطاق والملكية الأصلية الصريحة للتخزين والطوابع الزمنية ومفاتيح معرفات Classic القياسية

يكشف الملف الشخصي الاختياري LX_PORTABLE_CORE عن TXLSWorkbook و TXLSXWorkbook دون LCL على Linux و macOS. وقد رُجِم ونُفِّذ Linux x64 و macOS ARM64 الأصليان باستخدام Free Pascal 3.3.1؛ ويتطلب حارس إصدار المصدر 3.2.2 على الأقل، لكن هذا الحد الأدنى ليس ادعاءً بأن كل تركيبة مترجم وهدف أصليين قد تحقَّق منها

ضع cthreads و cwstring قبل وحدات HotXLS، وأضف Lib إلى مسارَي الوحدات والتضمين، وعرِّف LX_PORTABLE_CORE للبناء كاملًا. ولا يتطلب تطبيق console أصلي Interfaces أو widgetset الخاص بـ LCL

اختر locale ‏UTF-8 مثبتًا في بيئة التطبيق عند العمل بمسارات ملفات يونيكودية. ويمكن لـ locale غير صالح أو غير UTF-8 أن يجعل تحويل أسماء ملفات RTL الأصلي ضائعًا؛ ويرفض مساعد التحقق تلك البيئة صراحةً بدل تغيير الـ locale أو تخمين صفحة كود

program NativeWorkbookExample;
{$mode delphiunicode}
uses
  cthreads, cwstring, SysUtils, lxHandleX;
var
  Workbook: TXLSXWorkbook;
begin
  Workbook:= TXLSXWorkbook.Create;
  try
    Workbook.Sheets.Add('Data').Cells[1, 1].Value:= 5;
    Workbook.Sheets[1].Cells[1, 2].Formula:= 'A1*2';
    if Workbook.Recalculate<> 1 then
      raise Exception.Create('Workbook calculation failed');
    if Workbook.SaveAs('native.xlsx')<> 1 then
      raise Exception.Create('Workbook save failed');
  finally
    Workbook.Free;
  end;
end.
المجالعقد النواة الأصلية
ملفات المصنفاتأنشئ وافتح وحرِّر واحسب واحفظ XLS ‏BIFF8 الكلاسيكي و XLSX والمجموعة الفرعية الموسعة المدعومة من XLSB والمجموعة الفرعية المدعومة من ODS عبر واجهات برمجة المصنف العامة، بفحوصات التحويل وحدود التنسيق القائمة لديها. كما تحقَّقت سجلات BIFF2 الكلاسيكية بترميزَي CP1252 و CP932 المعلنَيْن صراحةً عبر الاستيراد والتصدير إلى BIFF8 يونيكودي
اليونيكود والأسماءيحفظ نص المصنف دلالات UTF-16 وتستخدم مسارات الملفات UTF-8 عند الحدود الأصلية. وتستخدم هوية الاسم المعرف التطبيعَ القياسي Unicode 16 المثبَّت وطيّ الحالة الكامل لـ BMP، محافظةً على الرموز والعلامات والتمايزات التركية وهوية حالة الأحرف للنطاق التكميلي باستقلال عن locale المضيف؛ وتحتفظ الصيغ المؤهلة بنطاق ورقتها الدقيق. ولا يزال ترتيب نص ورقة العمل العادي يستخدم مقارنة locale الأصلية RTL
البنية التحتيةتُستخدم الأقسام الحرجة الأصلية ومعرفات الخيوط كاملة العرض وخيوط العمال الحقيقية والملفات المؤقتة الحصرية المسجلة والاستبدال الذري للملف الشقيق وبايتات العشوائية من نظام التشغيل دون محاكاة Windows
الضغط والتشفيرتبقى ZIP/الضغط و AES من Pascal المرفقة متاحة. ويمكن قراءة ملفات XLS الكلاسيكية RC4 و RC4 CryptoAPI وكتابتها أصليًا باستخدام بايتات عشوائية من نظام التشغيل. وتستخدم قراءات OOXML المشفرة الأصلية قارئ الملفات المركبة النقي؛ وتتطلب كتابة ملف مركب OOXML مشفر نظامَ Windows وترفع استثناء منصة صريحًا على Unix الأصلي
دوال REGEX للصيغيُرجَم الـ backend الثابت المثبَّت PCRE2 ‏UTF-16 على الهدف الأصلي بمترجم C الخاص به. نفّذ sh Lib/thirdparty/build-pcre2-unix.sh قبل ترجمة التطبيقات التي تتضمن محرك الصيغ؛ وتتوفر أهداف ثابتة لـ Linux x64 و macOS ARM64
خدمات Windowsترفع الوصول إلى الحافظة وتفعيل COM في Windows ومزودات استعلام ADO/WinHTTP المدمجة والتقاط هندسة GDI وفك ترميز صور خلفية HTML والتصدير إلى PDF القديم استثناءً EXLSPlatformUnsupported عند حدودها الصريحة. وتبقى مزودات الاستعلام المخصصة ومزودات النص قابلة للاستخدام
المكونات القديمةيتاح نموذج المصنف الكلاسيكي وقارئ/كاتب BIFF في النواة الأصلية. وتبقى حزمة وقت تشغيل LCL ومكونات تصدير مجموعات البيانات/الشبكات وعناصر التحكم المرئية مكونات Windows/LCL. وترفع أساليب الحافظة الكلاسيكية والتصدير إلى HTML والتصدير إلى PDF القديم استثناءاتِ منصة صريحة على Unix الأصلي
صيغ النص البايتيةتعيد الدوال التي تتطلب صفحة كود ANSI/DBCS النشطة في Windows نتيجةَ صيغة غير مدعومة صريحة (#NAME?) على Unix الأصلي؛ ولا يُختار بديل ضمني للـ locale أو صفحة الكود

تحتفظ أساليب الفتح والحفظ بعقود رموز النتيجة والتشخيص العادية لديها. ويمكن للاستدعاءات المباشرة عبر حدود المنصة رفع EXLSPlatformUnsupported؛ فتعامل مع هذا الاستثناء عند استدعاء خدمة خاصة بـ Windows من شيفرة تطبيق مشتركة

تحقق أصلي قابل لإعادة الإنتاج

شغّل مساعد التحقق على الضيف الأصلي بأدوات Free Pascal القائمة و Python 3 ومترجم C أصلي. واختر مجلد إخراج جديدًا أو فارغًا خارج شجرة المصادر على نظام ملفات الضيف

python3 Tests/Lazarus/run_native_core.py --fpc /path/to/fpc --output /guest-local/hotxls-validation
python3 Tests/Lazarus/run_native_core.py --fpc /path/to/fpc --config /path/to/fpc.cfg --output /guest-local/hotxls-validation-2

ينسخ المساعد مدخلات المصدر ويحسب hash لها، ويطبّع أسماء ملفات وحدات Pascal في نسخة البناء الخاصة لبحث أسماء ملفات FPC الحساس لحالة الأحرف، ويبني PCRE2 محليًا، ويشغّل شهود النواة و AES والضغط و REGEX والمصنف العام والتكامل. ويحفظ بيانات المصادر الوصفية وسجلات المترجم والنتائج المُنتَجة والإخفاقات دون تغيير الشجرة أو تثبيت أدوات أو تعديل إعدادات المترجم. وتستهدف بناءات macOS ARM64 صراحةً macOS 11 أو أحدث

تتضمن شهود التكامل المسارات اليونيكودية ونماذج XLSB المؤلفة في Excel وcaches الصيغ وإعادة الحساب والفتحات المتكررة وملاحظات ODS المتناثرة والحماية ورفض التحويل المُدقَّق والإلغاءَ الذي يحفظ وجهات المستدعي وبحثَ الأسماء ذات النطاق الثابت واحتواءَ فشل العامل الحقيقي وبايتات العشوائية التشفيرية

عقود Classic XLS الأصلية

استخدم lxHandle لـ TXLSWorkbook الكلاسيكي و lxHandleX لـ TXLSXWorkbook. ويعيد Recalculate الكلاسيكي عدد أخطاء فصفر يعني النجاح؛ وأسلوب Calculate لديه يعيد نتيجة صيغة. وتتطلب إسنادات Formula لخلايا Classic البادئةَ =. وتحتفظ أساليب فتح وحفظ المصنف بنتيجة النجاح الراسخة 1

تستخدم تنفيذ التخزين الكلاسيكي الأصلي تدرجَ الملف المركب الحقيقي وهويات التدفقات، محافظًا على النطاقات المتداخلة وبيانات MiniFAT وسلاسل DIFAT الموسعة؛ وتُجسَّد حمولات التدفقات ويرفض الكاتب الإخراج المجمَّع خارج حدود المخزن/القطاع ذات الإشارة 32-بت المدعومة لديه قبل إصداره؛ وهذا ليس تنفيذ تخزين تدفقي متعدد الغيغابايتات

يوفر التخزين المركب الأصلي عمليات تدفق مباشرة وتعدادًا وmetadata وعمليات نسخ. وتعيد التراجع المعاملاتي وقفل المنطقة والنقل وأنماط الاستبعاد غير المدعومة أخطاء تخزين صريحة. ولا يحاكي خدمات COM أو الحافظة أو GDI في Windows

تُسلسَل عمليات الحفظ الأصلية للملفات الكلاسيكية قبل استبدال ملف شقيق مسجل ذريًا. وتجهِّز عمليات الحفظ إلى تدفق المستدعي الملفَ المركب الكامل قبل النسخ في الموضع الأصلي، محافظةً على البادئات وإخفاقات الإلغاء قبل الالتزام. ويبقى إشعار التقدم الأخير غير قابل للإلغاء. وتتبع كتابات مساعد التخزين المركب المباشر عقدَ الكتابة المباشرة العادي لديه بدل معاملة حفظ المصنف العامة

تستخدم خصائص الملخص وملخص المستند العادية مجموعاتِ خصائص OLE قياسية محودة بنص يونيكود وطوابع زمنية FILETIME بتوقيت UTC. وتبقى تدفقات الخصائص هذه نصًا صريحًا عندما تُشفَّر بيانات المصنف الكلاسيكي، ويسجل ترويسة RC4 CryptoAPI ذلك الاختيار صراحةً. وتتقاسم الأسماء المعرفة مفاتيح المعرفات القياسية المثبَّتة التي تستخدمها واجهة XLSX، مع الاحتفاظ بتهجئتها الأصلية ونطاق ورقتها الصريح. وتبقى بيانات رسم PNG/JPEG المرمزة متاحة للنموذج؛ ويتطلب تحويل الصور النقطية/ملفات التعريف الأصلي عارضًا مدعومًا منفصلًا وإلا رفع EXLSPlatformUnsupported

رجم Tests/Lazarus/HotXLSNativeClassicWorkbookSmoke.lpr بخيارات النواة الأصلية نفسها، ثم مرِّر Tests/Fixtures/classic-native/native-classic.xls ومسار إخراج ضيف محلي قابل للتصرف و Tests/Fixtures/classic-native/native-classic-encrypted.xls. وتغطي الضوابط caches المؤلفة في Excel وإعادة الحساب والأسماء اليونيكودية التامة وذهابًا وإيابًا عاديًا ومشفرًا وطوابعَ زمنية للخصائص مفكوكة باستقلال وفتحاتٍ متكررة وأكثر من 16 MB من بيانات SST وحفظ مخرجات المستدعي

ترميز بايتات BIFF القديم

تختار TXLSWorkbook.SetCodePage ترميزَ البايتات الصريح الذي يستخدمه SaveAs(..., xlExcel5)، و CP1252 هو الافتراضي؛ واستيرادُ ملف BIFF2–BIFF5 بسجل CODEPAGE غير صفري قابل للاستخدام يختار أيضًا تلك الصفحة لحفظات قديمة لاحقة

تستخدم تسميات الخلايا القديمة وثوابت نص الصيغ والمصفوفات وسلاسل الصيغ المخزنة والأسماء المعرفة وأسماء أوراق العمل ومراجعها وأسماء الخطوط وتنسيقات الأرقام وأسماء الأنماط والترويسات والتذييلات ونص التعليقات العادي تلك الصفحةَ المعلنة بدل locale نظام التشغيل أو UTF-8

تَعُدّ أطوال السجلات وإزاحات تدفق ورقة العمل البايتاتَ المرمزة؛ وتقتطع حدود التسمية القديمة البالغة 255 بايت وحدود literal الصيغ القائمة عند حد محرف كامل فقط، فلن يُقسَم محرف CP932 ثنائي البايت أبدًا؛ وترفض الأسماء والبيانات الوصفية ذات الطول البايتي الواحد النصَ المرمز الأطول من طولها القابل للتمثيل بدل إصدار طول غير صالح

يرفع النص العاجز عن ذهاب وإياب عبر صفحة الكود المختارة استثناءً EConvertError قبل أن يتحول صمتًا إلى محرف بديل أو تقريبي؛ فاختر صفحة تمثل نص المستند أو احفظ بـ BIFF8 للسلاسل اليونيكودية

تُجمَّع سلاسل caches الصيغ العابرة لسجلات CONTINUE بوصفها بايتات قبل فك الترميز، فيمكن لحد سجل أن يقسِم محرفًا ثنائي البايت دون إفساد القيمة المخزنة

يعيد تغيير الصفحة المختارة بناءَ بايتات الصيغ والأسماء المعرفة القديمة المُنمَّطة من نموذجها اليونيكودي؛ وتواصل حفظات BIFF8 استخدام اليونيكود وتبقى قيمة CODEPAGE على القرص لديها 1200

تحتفظ سجلات المخططات BIFF5 المستوردة بصفحة كودها الأصلية لفحص السلاسل المُنمَّطة والعناوين المرفقة، بما في ذلك بعد تعديل صفحة كود المصنف أو نسخ المخطط؛ وينقل الحفظ إلى صفحة مختلفة صراحةً النصَ المدعوم SeriesText والتسميات المخزنة العادية وسلاسل الصيغ والترويسات والتذييلات وأسماء الأوراق الخارجية للمصنف الحالي بدل إعادة تفسير البايتات المحفوظة تحت الإعلان الجديد

يرفض نص المخططات المستمر وترميزات الأوراق الخارجية القديمة غير المنمذجة وسجلات النص الثنائي القديم الـ opaque ترحيلَ صفحة الكود باستثناء EConvertError؛ ويرفض النص المدعوم غير القابل للتمثيل أيضًا، ويحفظ حفظ المصنف العام وجهةَ المستدعي قبل الالتزام؛ ولا يَعِد عقد النص هذا بتحويل كامل لمظهر المخطط الأصلي

تبدأ أسماء الأنماط المخصصة في BIFF5 مباشرة بعد الطول المرمز البايتي الواحد، بينما يحمل SeriesText في BIFF5 معرفًا وطولًا مرمزًا بايتيًا واحدًا دون علم يونيكود؛ ويضيف SeriesText في BIFF8 علمَ اليونيكود الخاص به، وينقل تحويلُ نص المخططات المدعوم ذلك السجل وإصدارَ BOF للمخطط معًا

تستخدم ترويسات وتذييلات المخططات BIFF5 غير الفارغة طولًا مرمزًا بايتيًا واحدًا بحد أقصى 255 بايت؛ وتستخدم سجلا LABEL و STRING المخزنان أطوالًا ثنائية البايت، بينما تستخدم ترويسات وتذييلات BIFF8 طولًا ثنائي البايت UTF-16 مع علم اليونيكود الخاص بها؛ ويفحص الترحيل تخطيط كل سجل فعليًا ويرفض ترويسة أو تذييلًا قديمًا كبيرًا باستثناء ERangeError قبل إلحاقه

يفسر HotXLS البايتات القديمة بصفحتها المعلنة على Windows و Linux و macOS؛ وأظهر بناء Excel 16.0 رقم 20430 المثبت قيدًا لدى المستقبل باستقلال: فقد فسّر البايتات القديمة بـ CP936 المحلي في Windows حتى بعد تغيير سجل CODEPAGE لملف أصلي وحده إلى CP1252 أو CP932، فالبايتات المعلنة الصحيحة لا تضمن نصًا مطابقًا في تلك إعدادات المستقبل

احفظ إعلان الترميز الفعلي للمستند واختبر التطبيق المستقبِل عند توزيع BIFF5 عبر إعدادات locale مختلفة؛ ويتجنب BIFF8 اليونيكودي حدَّ التوافق هذا للبايتات القديمة تحديدًا

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

يستخدم تحرير مصدر وحدات VBA صفحةَ كود البايتات المعلنة للمشروع ويحفظ البادئة الثنائية قبل إزاحة المصدر، بما يشمل بايتات null المضمنة؛ وهذا يغير نص المصدر المخزن ولا ينفذ وحدات الماكرو

يخطّط اليونيكود المضغوط في BIFF8 ذو fHighByte = 0 كل بايت مباشرةً إلى وحدة كود UTF-16 من U+0000 إلى U+00FF؛ وهو ليس CP1252 ولا UTF-8 ولا صفحة الكود القديمة للملف، حتى عندما يظهر سجل CODEPAGE غير قياسي في ملف BIFF8 خلاف ذلك

تحتفظ صيغ النص الأصلية بأطوال ومواضع UTF-16، بما يشمل وحدات كود أزواج الـ surrogate؛ وتستخدم LOWER و UPPER و SEARCH وفواصل TEXTBEFORE/TEXTAFTER غير الحساسة لحالة الأحرف وترويسات حقول قواعد البيانات والمعايير غير الحساسة لحالة الأحرف والمفاتيح النصية الديناميكية بيانات محارف اليونيكود للمترجم الأصلي بدل دوال حالة الأحرف ASCII فقط لـ locale الـ C للمضيف، بينما يحتفظ ترتيب ورقة العمل العادي بمقارنة الـ locale القائمة لديه

تستخدم مطابقة الأسماء المحلية في LET/LAMBDA الأصلية وتصنيف تخزين المصفوفات المحلية حالةَ أحرف واعية باليونيكود بالقدر نفسه، فيحل نظيرُ الحالة الارتباطَ الملتقط الصحيح ويحتفظ بشكل مصفوفته؛ وهذا لا يغير عقد هوية الأسماء المعرفة العامة المثبَّت

يحتفظ FindText و ReplaceText الكلاسيكيان غير الحساسين لحالة الأحرف بمطابقة محارف يونيكود للبحث الحرفي وبأحرف البدل على نمط Excel على FPC الأصلي؛ ولا يزال MatchCase يميز حالة الأحرف، ويحتفظ الاستبدال الحرفي بسلوك استبدال الكل، ويحتفظ استبدال أحرف البدل بسلوك أقصى-امتداد-إلى-اليسار القائم، وتبقى خلايا الصيغ مستبعدة

رجم Tests/Lazarus/HotXLSNativeLegacyEncodingSmoke.lpr بخيارات النواة الأصلية ومرِّر مجلد إخراج قابل للتصرف يليه Tests/Fixtures/legacy-encoding/native-biff5-cp936-chart.xls؛ ويفحص الشهود بايتات CP1252 و CP932 و CP936 المعلنة باستقلال، وكل إزاحة ورقة عمل، وتغييرات صفحة الكود، وحدود الاستمرار ثنائية البايت، واستيراد BIFF8 المضغوط، وحساب الصيغ، ونص مخطط مؤلف أصليًا، وحفظ وجهة المستدعي عند الفشل

المثبّت الكامل

يكتشف المثبّت الكامل Lazarus ويدعم التثبيت من دون RAD Studio. اختر Lazarus / Free Pascal في صفحة تكامل IDE لتثبيت حزمة وقت التشغيل ووحدات التوافق وسكربتات البناء؛ ويكون هذا الخيار محددًا افتراضيًا عندما يكون Lazarus هو IDE الوحيد المكتشف

في صفحة الترجمة بعد التثبيت، اختر حزمة وقت التشغيل الخاصة بـ Free Pascal للمعمارية Win32 أو Win64. يكون الهدف متاحًا عندما تُكتشف وحدات المترجم وRTL وLCL وLazUtils الخاصة به؛ ويمكنك مع ذلك تثبيت مصادر الحزمة عندما يكون الهدف غير متاح وترجمتها لاحقًا

الحزمة خاصة بوقت التشغيل فقط وتُضاف بوصفها تبعية للمشروع في Lazarus. لا يترجم المثبّت نماذج العرض التجريبية لـ VCL باستخدام Free Pascal

البناء والاختبار

افتح Lib/FPC/HotXLSLaz.lpk في Lazarus وترجم حزمة وقت التشغيل، أو نفّذ هذه الأوامر من مجلد HotXLS

build-FPC-Lib.cmd Win64
Tests\Lazarus\Run-HotXLSLazarusSmoke.cmd Win64
build-FPC-Lib.cmd Win32
Tests\Lazarus\Run-HotXLSLazarusSmoke.cmd Win32

اضبط LAZARUS_DIR لاختيار عملية تثبيت؛ ويمكن لـ FPC_EXE وLAZBUILD_EXE اختيار ملفَّي تنفيذ محددين للمترجم وباني الحزم عند الحاجة

يجب أن تتضمن عملية التثبيت المختارة FPC ووحدات LCL/LazUtils المترجمة للمعمارية الهدف؛ وتُحفظ المخرجات وإعدادات باني الحزم في مجلدات منفصلة لكل معمارية

إعداد التطبيق

أضف Lib وLib/FPC إلى مسار بحث الوحدات وLib إلى مسار بحث include، أو أضف حزمة وقت التشغيل بوصفها تبعية لمشروع Lazarus

ضع Interfaces قبل وحدات HotXLS في قائمة uses للتطبيق، بما في ذلك التطبيقات النصية؛ فهذا يهيئ widgetset الخاص بـ LCL وتحويل UTF-8 عند حدود RTL/LCL

program WorkbookExample;
{$mode delphiunicode}
uses
  Interfaces, SysUtils, lxHandleX;
var
  Workbook: TXLSXWorkbook;
begin
  Workbook:= TXLSXWorkbook.Create;
  try
    Workbook.AddSheet('Data');
    Workbook.Sheets[1].Cells[1, 1].Value:= 'Hello';
    if Workbook.SaveAs('example.xlsx')<> 1 then
      raise Exception.Create('Workbook save failed');
  finally
    Workbook.Free;
  end;
end.

تختار وحدات مصدر HotXLS داخليًا دلالات يونيكود الخاصة بـ Delphi، فتبقى السلاسل والمحارف ونص الصيغ محتفظة بسلوك UTF-16؛ ويمكن لشيفرة التطبيق أن تستخدم نمط Pascal المفضل لديها

تفاصيل التوافق