تفعيل تطوير وتصحيح أخطاء إضافات سطح المكتب لبرنامج ONLYOFFICE

لا تحتاج إلى تفعيل خيار تطوير الإضافات بشكل منفصل في محررات ONLYOFFICE لسطح المكتب. أنشئ إضافة، وثبّت حزمتها .pluginعبر مدير الإضافات، وشغّل تطبيق سطح المكتب --ascdesktop-support-debug-infoعند الحاجة إلى أدوات تصحيح الأخطاء. يستخدم محرر سطح المكتب ومحرر الويب إجراءات تحميل مختلفة، لذا ابدأ باتباع سير العمل الخاص بسطح المكتب الموضح أدناه.

قم بإعداد مشروع إضافة صغير

تنطبق هذه التعليمات على محررات سطح المكتب ONLYOFFICE لأنظمة التشغيل Windows و macOS و Linux. استخدم نسخة محدثة من البرنامج ومحرر أكواد للملفات النصية. تُعامل الوثائق الرسمية تثبيت الإضافات يدويًا وتصحيح الأخطاء من قِبل المطورين كخاصيتين منفصلتين؛ ولا يُشترط استخدام متجر الإضافات لتطوير واختبار إضافة محلية. يُعد مثال "Hello World" فحصًا أوليًا مفيدًا لأنه يعزل تحميل الإضافات عن الخدمات الأكثر تعقيدًا.

1. أنشئ مجلد المصدر

أنشئ مجلدًا باسم hello-world-plugin. أضف إليه config.jsonملف بيان ونقطة index.htmlدخول. يمكنك إضافة icon.pngصورة إذا كان ملف البيان يشير إليها. احتفظ بالمجلد خارج مجلد التطبيق المُثبّت حتى لا تُستبدل ملفات العمل بتحديثات البرامج.

2. حدد البيان وقم بإنشاء معرّف فريد عالمي خاص بك

يُحدد ملف البيان لبرنامج ONLYOFFICE ملف HTML الذي يجب تحميله والمحررات التي يمكنها تشغيل الملحق. يدعم المثال التالي محرر المستندات. استبدل معرّف GUID النموذجي بمعرّف UUID جديد قبل التثبيت: شغّل الأمر New-Guidفي Windows PowerShell أو uuidgenعلى macOS أو Linux، ثم قم بتنسيق القيمة asc.{YOUR-UUID}. يحتاج كل ملحق إلى معرّف خاص به.

{
  "name": "Hello World",
  "guid": "asc.{12345678-1234-1234-1234-1234567890AB}",
  "version": "1.0.0",
  "variations": [{
    "url": "index.html",
    "icons": ["icon.png"],
    "isViewer": false,
    "EditorsSupport": ["word"]
  }]
}

استخدم تنسيق JSON صحيحًا: بدون فواصل زائدة، مع أقواس متطابقة، وملف حقيقي لكل نقطة دخول أو أيقونة مُشار إليها. بالنسبة لملحقات جداول البيانات أو العروض التقديمية، استخدم القيم المناسبة بدلًا من افتراض ظهور ملحق خاص بالمستندات فقط في كل مكان. قارن البنية مع دليل البدء السريعEditorsSupport الرسمي لبرنامج "Hello World" .

3. تنفيذ نقطة الدخول

في index.htmlملف `..`، قم بتحميل مكتبة واجهة برمجة تطبيقات ONLYOFFICE الإضافية، وأضف زرًا، واجعل الزر يستدعي الدالة `..` . يوفر مثال البدء السريعwindow.Asc.plugin.executeMethod("PasteText", ["Hello World!"]) من الشركة المصنعة كود HTML كاملًا ورابطًا للمكتبة؛ لذا فإن نسخ هذا المثال أكثر أمانًا من محاولة تخمين التهيئة أو صيغة واجهة برمجة التطبيقات. احفظ الملف بصيغة UTF-8. إذا كنت تخطط للعمل دون اتصال بالإنترنت، فتذكر أن الصفحة التي تستورد مكتبة الإضافات أو غيرها من الموارد من رابط على الإنترنت لا تزال بحاجة إلى تحميل هذه الموارد.

قم بتثبيت وتشغيل إضافة التطوير الخاصة بك

4. أنشئ ملف .plugin

حدد الملفات داخل مجلد المصدر، واضغطها في ملف ZIP، ثم أعد تسمية امتداد ZIP من . .zipإلى .plugin. يجب أن يحتوي جذر الأرشيف على الملفين config.jsonو index.html، وليس مجلدًا فرعيًا آخر hello-world-plugin. في نظام ويندوز، فعّل امتدادات أسماء الملفات في مستكشف الملفات لتجنب إنشاء ملف عن طريق الخطأ . تدعم تعليمات تثبيت Desktop Editorshello-world.plugin.zip الرسمية التثبيت اليدوي صراحةً دون الحاجة إلى اتصال بمتجر Marketplace.

5. استورد الحزمة من مدير الإضافات

افتح مستندًا قابلاً للتحرير في محررات ONLYOFFICE Desktop. اختر الإضافات > مدير الإضافات > إضافاتي > تثبيت الإضافة يدويًا . قد يختلف مظهر المدير باختلاف الإصدار، ولكن هذا الإجراء هو مسار التثبيت اليدوي الموثق. وهو ليس إعداد عنوان URL الخاص بالمطورين في المتجر.

6. حدد الملف وتحقق من إدخاله في القائمة

حدد hello-world.pluginملف الأرشيف في نافذة الملفات وافتحه. ستظهر الإضافة المثبتة ضمن تبويب الإضافات. إذا لم تكن موجودة، فراجع ملف البيان، ومعرّف GUID، ونوع المحرر المدعوم، وجذر الأرشيف قبل تغيير إعدادات التطبيق. حاول إعادة فتح مستند بعد التثبيت إذا لم يتم تحديث القائمة فورًا.

7. اختبر الملحق في مستند مؤقت

افتح مستند اختبار فارغًا، وشغّل إضافة "Hello World" من تبويب الإضافات، واستخدم زرها. تأكد من ظهور عبارة "Hello World!" في المستند. هذا الإجراء يتجاوز مجرد التحقق من التثبيت، فهو يؤكد تحميل واجهة الإضافة ووصول استدعاء واجهة برمجة التطبيقات (API) الخاصة بها إلى المستند. تجنب اختبار الإضافات التي تُغيّر المحتوى على ملف لا يمكن استبداله.

تفعيل تصحيح الأخطاء لتطوير الإضافات

8. أعد تشغيل محررات سطح المكتب مع علامة التصحيح

أغلق برنامج ONLYOFFICE Desktop Editors تمامًا، ثم شغّل التطبيق من سطر الأوامر باستخدام خيار تصحيح الأخطاء الرسمي. استخدم الأمر المناسب لنظام التشغيل وموقع التثبيت لديك:

• موجه أوامر ويندوز: "%ProgramFiles%\ONLYOFFICE\DesktopEditors\DesktopEditors" --ascdesktop-support-debug-info
• لينكس (موقع الحزمة القياسي): "/opt/onlyoffice/desktopeditors/DesktopEditors" --ascdesktop-support-debug-info
• macOS: "/Applications/ONLYOFFICE.app/Contents/MacOS/ONLYOFFICE" --ascdesktop-support-debug-info

يستخدم أمر Windows المذكور أعلاه توسيع متغيرات موجه الأوامر، وليس صيغة PowerShell؛ في PowerShell، استدعِ الملف التنفيذي باستخدام مساره الكامل. إذا تم تثبيت تطبيقك في موقع غير قياسي، فاستبدل المسار الفعلي للملف التنفيذي. يمكنك أيضًا إضافة العلامة إلى حقل "الهدف" في اختصار سطح مكتب Windows. راجع أوامر وضع تصحيح أخطاء سطح المكتب في ONLYOFFICE لمزيد من التفاصيل حول النظام الأساسي.

بعد فتح المستند، انقر في منطقة التحرير واضغط على F1 ، أو انقر بزر الماوس الأيمن على حقل شريط الأدوات القابل للتحرير واختر "فحص العنصر" . في أدوات المطورين، اختر إطار iframe الخاص بالملحق لفحص رمز واجهة الملحق وسجلاته. يتم تشغيل الرمز المُمرر callCommandفي frameEditorالسياق، لذا بدّل الإطارات عند الضرورة. يشرح مرجع تصحيح أخطاء الملحق هذا الفرق وكيفية استخدام نقاط التوقف. قد يكشف التصحيح محتوى المستند وتفاصيل وقت التشغيل؛ لذا لا تُشارك السجلات الخام قبل مراجعتها.

تقصير دورة التحرير والاختبار دون تعديل المكونات الإضافية المدمجة

بعد التثبيت اليدوي، يقوم برنامج ONLYOFFICE بنسخ الملحق إلى مجلد يحمل اسمًا فريدًا (GUID) ضمن ملف تعريف المستخدم الخاص بك. المواقع الموثقة هي %LOCALAPPDATA%\ONLYOFFICE\DesktopEditors\data\sdkjs-plugins\على أنظمة Windows ~/Library/Application Support/asc.onlyoffice.ONLYOFFICE/data/sdkjs-plugins/و macOS و ~/.local/share/onlyoffice/desktopeditors/sdkjs-plugins/Linux. يُحذف الجزء الأول من اسم المجلد (GUID) asc.المستخدم في ملف البيان.

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

تحقق من إعدادات التطوير

ثلاثة فحوصات تدل على جاهزية سير العمل: ظهور الملحق المخصص ضمن "الملحقات" ، وإدراج اختبار "Hello World" نصًا في مستند جديد، وفتح أدوات المطورين بعد التشغيل مع تفعيل وضع التصحيح. في حال كانت الواجهة فارغة أو فشل التثبيت، تأكد من تحليل ملف البيان بصيغة JSON، وأن المعرّف الفريد العالمي (GUID) يبدأ بـ asc.، وأن الملحق index.htmlموجود في المسار النسبي المُعلن، وأن جميع الموارد المطلوبة متوفرة. يغطي دليل أخطاء الملحقات الرسمي هذه الأعطال الشائعة. لا يُعد تثبيت الملحق دليلاً على عمل جميع ميزاته؛ لذا كرر الفحص نفسه بعد كل تغيير في الكود.