كيفية تفعيل تطوير الإضافات في محررات سطح المكتب ONLYOFFICE

لا يوفر برنامج ONLYOFFICE Desktop Editors أي توثيق لخيار "تمكين تطوير الإضافات". تتمثل آلية العمل المعتمدة في تثبيت الإضافة الخاصة بك عبر مدير الإضافات، ووضعها في مجلد الإضافات المحلي، ويمكنك استبدال النسخة المثبتة برابط رمزي إلى مجلد المصدر الخاص بك. لفحص الأخطاء واستخدام نقاط التوقف، شغّل تطبيق سطح المكتب مع علامة التصحيح الموثقة. هذه خطوات منفصلة: يُتيح وضع التصحيح الوصول إلى أدوات المطور، بينما يُتيح تثبيت الإضافة أو ربطها استخدامها للمحرر.

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

اختر سير عمل تطوير المكونات الإضافية

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

قم بإعداد ملفات الملحق

ابدأ بإنشاء مجلد إضافات محلي يحتوي على الأقل على الملفات المطلوبة لإضافتك، بما في ذلك config.jsonملفات index.html. يجب أن يحتوي ملف الإعدادات على معرّف فريد عالمي (GUID) صالح للإضافة، وأن يشير إلى صفحة دخول الإضافة ومواردها باستخدام مخطط إضافات ONLYOFFICE. استخدم نماذج الإضافات الرسمية أو وثائق واجهة برمجة التطبيقات (API) للاطلاع على المخطط الكامل؛ إذ قد يؤدي معرّف فريد عالمي (GUID) غير صحيح، أو مسار معطوب، أو إعدادات غير صالحة إلى منع ظهور الإضافة.

عادةً ما يكون مُعرّف GUID config.jsonبالشكل التالي asc.{YOUR-GUID}: . يستخدم مُحرّرو سطح المكتب مُعرّف GUID كاسم لمجلد الإضافة، لكنهم يحذفون asc.البادئة. احتفظ بنفس مُعرّف GUID في دليل المصدر، والأرشيف، ومسار التثبيت. لا تُعِد استخدام مُعرّف GUID الخاص بإضافة مُدمجة أو إضافة أخرى مُثبّتة.

قم بتثبيت الملحق لأول مرة

1. ضع ملفات الملحق ومجلداته الفرعية في ملف مضغوط (ZIP). يجب أن تكون الملفات نفسها في جذر الملف المضغوط، وليس داخل مجلد مشروع إضافي.
2. قم بتغيير امتداد الأرشيف من .zipإلى .plugin.
3. افتح برنامج ONLYOFFICE Desktop Editors، وحدد علامة التبويب Plugins ، ثم انقر فوق Plugin Manager .
4. افتح "إضافاتي" ، واختر "تثبيت الإضافة يدويًا" ، ثم حدد .pluginالملف، وقم بالتأكيد.

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

استخدم رابطًا رمزيًا لتسريع عملية التكرار

بعد التثبيت الأولي، يحفظ برنامج Desktop Editors نسخةً منه في sdkjs-pluginsمجلد. استبدل هذه النسخة برابط رمزي إلى مجلد المصدر لتتمكن من تعديل ملفات العمل مباشرةً. أغلق برنامج Desktop Editors قبل تغيير مجلد الإضافات التجريبية المُثبّتة. احتفظ بنسخة احتياطية أو تأكد من سلامة مجلد المصدر، ثم احذف المجلد الذي يطابق معرّف GUID الخاص بإضافة الاختبار فقط.

داخل الدليل، يكون اسم الرابط هو المعرّف الفريد العالمي (GUID) بين قوسين بدون asc.البادئة. على سبيل المثال، إذا كان المعرّف الفريد العالمي (GUID) الخاص بالتكوين هو asc.{91EAC419-EF8B-440C-A960-B451C7DF3A37}، فسيكون اسم المجلد أو الرابط هو {91EAC419-EF8B-440C-A960-B451C7DF3A37}.

ويندوز

افتح موجه الأوامر كمسؤول إذا كان حساب ويندوز الخاص بك أو سياسة النظام تتطلب ذلك. بعد إغلاق المحررات ونقل مجلد test-plugin المثبت إلى مكان آخر، أنشئ رابط الدليل التالي:

mklink /D "%LOCALAPPDATA%\ONLYOFFICE\DesktopEditors\data\sdkjs-plugins\{YOUR-GUID}" "C:\path\to\your\plugin"

استبدل كلا العنصرين النائبين بمعرف GUID والمسار الكامل إلى دليل المصدر. يجب ألا يكون رابط الوجهة موجودًا بالفعل.

نظام التشغيل macOS

ln -s "/path/to/your/plugin" "$HOME/Library/Application Support/asc.onlyoffice.ONLYOFFICE/data/sdkjs-plugins/{YOUR-GUID}"

لينكس

ln -s "/path/to/your/plugin" "$HOME/.local/share/onlyoffice/desktopeditors/sdkjs-plugins/{YOUR-GUID}"

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

تشغيل محررات سطح المكتب باستخدام أدوات المطورين

لتصحيح أخطاء أحد المكونات الإضافية، أغلق برنامج Desktop Editors تمامًا ثم أعد تشغيله --ascdesktop-support-debug-infoباستخدام الأمر المناسب لنظام التشغيل الخاص بك؛ إذا قمت بتثبيت التطبيق في موقع مخصص، فقم بتعديل مسار الملف التنفيذي.

ويندوز

قم بتشغيل هذا الأمر في موجه الأوامر:

"%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

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

يُبقي الخيار الاختياري --ascdesktop-support-debug-info-keep=1وضع التصحيح مُفعّلاً بين عمليات التشغيل. لإيقاف الحالة الدائمة، شغّل البرنامج باستخدام الأمر --ascdesktop-support-debug-info-keep=0`--`؛ استخدم --ascdesktop-support-debug-info-keep=defaultالأمر `--` للعودة إلى الحالة الافتراضية. تُعدّ أدوات المطورين الدائمة مُريحة على جهاز اختبار مُخصّص، ولكن تركها مُفعّلة على محطة عمل مُشتركة يُضيف فوضى ويُبقي أدوات الفحص مُتاحة عندما لا تحتاج إليها.

تأكد من أن إعدادات التطوير تعمل

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

إذا كان الملحق مفقودًا، فتأكد من وجوده في جذر الأرشيف، config.jsonوأنّ index.htmlالمعرّف الفريد العالمي (GUID) صالح، وأنّ المجلد يستخدم المعرّف الفريد العالمي بدون asc.البادئة. تأكد من أنّ الرابط يشير إلى دليل المصدر وليس إلى دليل رئيسي يحتوي عليه. إذا ظهر الملحق ولكنه يعمل كإصدار قديم، فأغلق المستند وأعد فتحه ليُعيد المحرر تحميل الملفات المرتبطة.

ما لا يتيحه هذا الإعداد

لا يُعدّ خيار تصحيح الأخطاء على سطح المكتب مفتاحًا عامًا لصلاحيات تطوير الإضافات. يُتيح تثبيت ملف مضغوط أو وضع مجلد في دليل الإضافات المدعومة استخدام تلك الإضافة؛ بينما يُتيح خيار تصحيح الأخطاء الوصول إلى أدوات الفحص. وبالمثل، لا تنطبق تعليمات تحميل إضافة عبر عنوان URL في محرر الويب تلقائيًا على محررات سطح المكتب. استخدم آلية التثبيت وتصحيح الأخطاء الخاصة بسطح المكتب المذكورة أعلاه.

تتعلق هذه التعليمات بالإضافات الخاصة بمحررات ONLYOFFICE المكتبية. ولا تشرح كيفية تفعيل الإضافات في DocSpace، أو كيفية تهيئة الإضافات من جانب الخادم في ONLYOFFICE Docs، أو كيفية نشر إضافة في المتجر. للحصول على معلومات حول هذه العمليات، يُرجى الرجوع إلى وثائق المنتج الرسمية ذات الصلة.

المراجع الرسمية

• أونلي أوفيس: تطوير الإضافات
• أونلي أوفيس: تطوير إضافات لمحررات سطح المكتب
• أونلي أوفيس: تثبيت واختبار الإضافات في محررات سطح المكتب
• ONLYOFFICE: تشغيل محررات سطح المكتب في وضع التصحيح
• أونلي أوفيس: تصحيح أخطاء الإضافات في محررات سطح المكتب
• أونلي أوفيس: أمثلة رسمية للملحقات ومستودع المصادر