حوّل وثائق Office لـ PDF وPNG فـ Node.js باستعمال LibreOffice Kit

نظرة عامة

@deepseek-ai/libreoffice-kit هي حزمة Node.js لتحويل مستندات Office وعرضها باستعمال محرّكات LibreOffice مصغّرة ومبنية مسبقاً. صُمّمت للتطبيقات اللي خاصها تخطيط مستندات متوقَّع، ونص مقروء، وتحكّم صريح فالخطوط، وتنفيذ بلا إنترنت ومن غير الاعتماد على نسخة LibreOffice منصَّبة بشكل مستقل.

الحزمة كتدعم تحويل Office إلى PDF، والعرض المباشر بصيغة PNG، وإعادة حساب جداول البيانات. تقدر تستعملها فخدمة Node.js، أو تطبيق سطح المكتب، أو مهمة معالجة دفعية، أو أي مسار آخر لمعالجة المستندات. التفويض، وتخزين الملفات، وواجهات المعاينة كيبقاو من مسؤولية التطبيق.

الميزات الرئيسية

• تحويل مستندات Office: تصدير مستندات Writer وCalc وImpress المدعومة إلى PDF.
• عرض الصفحات: عرض مدخلات Office أو PDF مباشرةً على شكل صفحات PNG.
• إعادة حساب جداول البيانات: إعادة حساب المصنفات وحفظ النتيجة المحدَّثة.
• معالجة واعية بالخطوط: اكتشاف خطوط النظام أو فهرسة مجلدات الخطوط المهيَّأة بشكل صريح.
• استبدالات قابلة للتهيئة: استعمال تفضيلات احتياطية لعائلات الخطوط اللاتينية والصينية المبسطة الشائعة.
• الإبلاغ عن الخطوط الناقصة: الإبلاغ عن عائلات الخطوط غير المتوفرة والمصرَّح بها فبيانات OOXML القابلة للقراءة.
• محرّكات بلا إنترنت: استعمال المحرّكات الأصلية المضمَّنة فأنظمة macOS وWindows المدعومة، أو محرّك WASM على Linux.
• التحكّم فالموارد: تطبيق حدود للمهلة الزمنية وفهرسة الخطوط أو تحميلها.
• واجهات سطر الأوامر وNode: تشغيل التحويلات من الطرفية أو دمجها فشفرة التطبيق.

اعتبارات المستندات المدعومة

كيحتافظ المحرّك بفلاتر Writer وCalc وImpress وOOXML وOffice الثنائي، ومكوّنات الرسوم البيانية والتخطيط والرسم، ودعم تصدير PDF. الملفات الثنائية .doc و.xls و.ppt مدعومة إلا كانت مستندات OLE مركّبة حقيقية، بحال ملفات Microsoft Office 97–2003.

ملفات RTF أو HTML اللي غير تبدّل الامتداد ديالها لامتداد Office ثنائي ما كتتقبلش. وملفات .wps حتى هي ما كتتقبلش.

بالنسبة لمستندات OOXML، كيعرض missingFonts العائلات غير المتوفرة اللي لقاها فملفات XML القابلة للقراءة داخل المستند. الصيغ الثنائية كترجع لائحة خاوية، مع أن LibreOffice كيبقى كيدير المطابقة ديال الخطوط ديالو. وبالتالي فالنتيجة ماشي تقرير كامل على الحروف الناقصة.

المتطلبات الأساسية والتثبيت

خاصك Node.js بالإصدار 22.19.0 أو أحدث. ثبّت الإصدار 0.1.3 من npm:

npm install @deepseek-ai/libreoffice-kit@0.1.3

الحزمة كتستعمل تبعيات اختيارية باش تثبّت المحرّك المطابق لنظام التشغيل والبنية المعمارية الحالية. ما كتجمعش LibreOffice وقت التثبيت، وما كتنزّلش محرّكات إضافية، وما كتقلبش على تطبيق LibreOffice منصَّب من طرف المستخدم.

اختيار محرّك المنصة

• macOS بمعالجات Apple Silicon: كيستعمل @deepseek-ai/libreoffice-kit-darwin-arm64.
• macOS بمعالجات Intel: كيستعمل @deepseek-ai/libreoffice-kit-darwin-x64.
• Windows ARM64: كيستعمل @deepseek-ai/libreoffice-kit-win32-arm64 وكيحتاج Node.js بنسخة ARM64 وMicrosoft Visual C++ v14 ARM64 Redistributable.
• Windows x64: كيستعمل @deepseek-ai/libreoffice-kit-win32-x64 وكيحتاج Microsoft Visual C++ v14 x64 Redistributable.
• Linux: كيستعمل عادةً المحرّك المشترك @deepseek-ai/libreoffice-kit-wasm.

macOS وWindows كيحتاجو الحزم الأصلية المطابقة ديالهم وما كيرجعوش لمحرّك WASM. إلا كان شي محرّك ضروري ناقص أو خاسر، createConverter كيرفض بخطأ unavailable. والتحويل الفاشل حتى هو ما كيطلقش تبديل أوتوماتيكي لمحرّك آخر.

استعمال واجهة سطر الأوامر

التثبيت كيزيد الأمر dsoffice. ملي كيكون منصَّب محلياً فمشروع، شغّلو عبر npm exec.

عرض صفحة بصيغة PNG

الأمر التالي كيعرض الصفحة 1 من مستند DOCX داخل مجلد الإخراج report-pages:

npm exec -- dsoffice render \
  --input report.docx \
  --output-dir report-pages \
  --pages 1

تحويل مستند Office إلى PDF

npm exec -- dsoffice convert \
  --input report.docx \
  --output report.pdf

إعادة حساب جدول بيانات

استعمل أمر إعادة الحساب ملي خاص الصيغ تتحسب ويتحفظ المصنف المحدَّث:

npm exec -- dsoffice recalculate \
  --input budget.xlsx \
  --output recalculated.xlsx

تحويل المستندات عبر واجهة Node.js

للدمج مع التطبيق، استورد createConverter، وأنشئ محوِّلاً، وشغّل العملية، وتخلّص من المحوِّل داخل كتلة finally.

import { createConverter } from '@deepseek-ai/libreoffice-kit';

const converter = await createConverter({
  timeoutMs: 120_000,
});

try {
  const result = await converter.render({
    inputPath: '/private/work/document.docx',
    outputPath: '/private/work/document.pdf',
  });

  console.log('Backend:', result.backend);
  console.log('Missing fonts:', result.missingFonts);
} finally {
  await converter.dispose();
}

فهاد المثال، ملف PDF اللي تْولّد كيتكتب فـ outputPath. والنتيجة المرجَّعة كتحدّد الواجهة الخلفية المختارة وكتضم أسماء عائلات الخطوط الناقصة اللي تكتاشفات فالمستند.

متطلبات المسارات والإخراج

• دَوّز المسارات المطلقة ديال الإدخال والإخراج.
• استعمل مجلدات خاصة، مملوكة ومتحكَّم فيها من طرف التطبيق اللي كينادي.
• خاص ملف الإخراج المطلوب ما يكونش موجود من قبل.
• خلي التنظيف فبلوك finally باش يتنقّاو الـprocesses الأصلية، والـworkers، والـprofiles، والموارد المؤقتة.

إعداد الخطوط المخصّصة

افتراضياً، الحزمة كتلقا الخطوط فالمجلدات التقليدية ديال خطوط النظام والمستخدم. وتقدر عوض ذلك تحدد الجذور بشكل صريح عبر fontDirectories:

import { createConverter } from '@deepseek-ai/libreoffice-kit';

const converter = await createConverter({
  timeoutMs: 120_000,
  fontDirectories: [
    '/absolute/path/to/company-fonts',
    '/absolute/path/to/cjk-fonts',
  ],
});

try {
  const result = await converter.render({
    inputPath: '/private/work/presentation.pptx',
    outputPath: '/private/work/presentation.pdf',
  });

  if (result.missingFonts.length > 0) {
    console.log('Unavailable families:', result.missingFonts);
  }
} finally {
  await converter.dispose();
}

جذور الخطوط المخصّصة كتعوّض لائحة الاكتشاف الافتراضية، وما كتزيدش عليها. الحزمة كتستعمل fontkit باش تفحص الميتاداتا وتغطية الحروف، ومن بعد كتمدّ المحرّك بالملفات المختارة فشكل البايتات الأصلية ديال الخطوط.

ما كاين حتى تجميع ديال الخطوط مدموج ولا كيتحمّل. النشر ديالك خاصو يوفّر الخطوط المناسبة ويحترم حقوق إعادة توزيعها. الحاويات الخفيفة غالباً خاصها تثبّت الخطوط أو يتضبط فيها مجلد صريح للخطوط.

سلوك الخطوط البديلة

الإعداد الافتراضي ديال fontFallbacks فيه تفضيلات لعائلات لاتينية شائعة ولعائلات الصينية المبسطة. فيه Carlito كبديل ملي Calibri ما يكونش متوفر، وCaladea ملي Cambria ما تكونش متوفرة. مجموعات الخطوط البديلة اللي كيحددها المستعمل كتعاوض الإعدادات الافتراضية، وما كتقدرش تختار إلا الخطوط المتوفرة فعلاً؛ وما كتثبّتش الخطوط.

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

نصائح تشغيلية متقدمة

عاود استعمل المحوّلات بحذر

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

كل عملية تحويل ما زالت كتملك process أصلي جديد أو worker جديد ديال Node، وprofile خاص بها. الإلغاء والتخلّص كيتسناو خروج المحرّك والتنظيف.

حدّد ميزانيات موارد الخطوط

مجلدات الخطوط الكبيرة أو غير الموثوقة خاصها تكون محدودة باستعمال أدوات التحكم المتاحة فالخطوط:

• maxFontFiles كيحدّد عدد ملفات الخطوط المفهرسة.
• maxFontFileBytes كيحدّد حجم كل ملف خط.
• maxLoadedFontBytes كيحدّد المجموع الإجمالي لبيانات الخطوط المحمّلة.

كل عملية كتعاود تكتاشف الخطوط وكتعاود تتحقق منها. الميتاداتا اللي ما تبدلاتش تقدر تتشارك عبر مخازن المصنع المؤقتة ديال المحوّل. راجع توثيق مخزن ميتاداتا الخطوط باش تعرف إعدادات التخزين المؤقت وتفاصيل إبطال الصلاحية.

خطّط لتوفّر الخطوط فـLinux

محرّك WASM ديال Linux كيستعمل غير الخطوط المستوردة. إلا ما كان حتى خط قابل للاستعمال متوفر، التحويل كيرفض بخطأ unavailable. لذلك خاص الحاويات تثبّت الخطوط المناسبة أو تركّب مجلد خطوط مراقَب وتدوز المسار المطلق ديالو إلى fontDirectories.

ما تفترضش نفس مخرجات Office

المعالجة اللي كتراعي الخطوط كتحسّن التحكم فاختيار العائلات، ولكن ما كتضمنش مخرجات مطابقة لـMicrosoft Office ولا مخرجات مطابقة بين المحرّكات الأصلية ومحركات WASM. مقاييس الخطوط تقدر تبدّل فواصل الأسطر، وتقسيم الصفحات، وأبعاد الجداول، وتفاصيل أخرى فالتخطيط.

باش تدير مقارنات مفيدة، استعمل نفس بايتات الوثيقة، ونفس الخطوط، ونفس خيارات التصدير. LibreOffice الأصلي يقدر يختار العائلات الأصلية المثبّتة والبدائل المتوافقة فالمقاييس قبل التعويضات المكوّنة، وكيقوم باختيار الوجه ديالو.

اعتبر التحويل حدوداً لمعالجة الوثائق

المكتبة كتقوم بالتحويل والتصيير، ولكن ما كتوفّرش التفويض، ولا التخزين، ولا واجهة للمعاينة. التطبيقات خاصها تتحقق من الولوج، وتعزل الملفات المملوكة للمستعمل، وتختار مجلدات عمل خاصة، وتطبّق حدوداً مناسبة للوقت والموارد على مهام التحويل.

التطوير والتحقق

إلا كنت كتساهم فالمستودع نفسه، تقدر تشغّل اختبارات الميتاداتا والوحدات والحزمة بلا ما تبني LibreOffice:

pnpm verify:metadata
pnpm test
pnpm test:packaging

اختبارات المحرّك الحقيقية كتحتاج كذلك بناء الـadapter، وحمولات المحرّك المحضّرة، وLIBREOFFICE_RUNTIME_ENTRY كيشير للمسار المطلق ديال packages/entry/lib/index.js. بناءات المحرّك خاصها تستعمل إصدارات المصدر وسلسلة الأدوات المحددة فالمستودع.

الخلاصة

كتوفّر @deepseek-ai/libreoffice-kit طريقة عملية لدمج تحويل وثائق Office، وإعادة حساب جداول البيانات، وتصْيير PNG فالتطبيقات الحديثة ديال Node.js. الميزة الرئيسية ديالها هي التعامل الصريح مع الخطوط، مع محرّكات أصلية ومحرّكات WASM محضّرة كتخدم بلا اتصال. باش تحصل على نتائج موثوقة، وفّر الخطوط المطلوبة، واستعمل مسارات مطلقة وخاصة، وحدّد الحدود المناسبة، وفحص missingFonts، ودائماً تخلّص من المحوّلات من بعد الاستعمال.

بالنسبة للإلغاء، والتعامل المفصّل مع الأخطاء، وضوابط الموارد الإضافية، راجع توثيق Node API.