تصحيح أخطاء اضافات ONLYOFFICE: دليل عملي

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

حول اضافات ONLYOFFICE

يتيح لكم ONLYOFFICE توسيع وظائف محرريه من خلال الاضافات. هذه الاضافات عبارة عن صفحات HTML مضمنة في المحرر وتستخدم واجهة برمجة التطبيقات (API) للتفاعل معه. يعد فهم بنية الاضافة وطرق تصحيح الأخطاء مفتاحاً للتطوير الناجح.

بنية الاضافة

تتكون اضافة ONLYOFFICE النموذجية من الملفات التالية:

• config.json: ملف تكوين يحدد المعلومات الأساسية حول الاضافة.
• index.html: صفحة HTML الرئيسية للاضافة.
• scripts: دليل يحتوي على ملفات JavaScript المطلوبة لوظائف الاضافة.

تتوفر بنية مفصلة وأمثلة هنا.

تصحيح أخطاء الاضافات في محررات الويب

لتصحيح أخطاء الاضافات في إصدار الويب لمحرر ONLYOFFICE، اتبعوا الخطوات التالية:

• أضيفوا أمر debugger إلى النص البرمجي الخاص بكم.

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

• اضغطوا على F12 لفتح وحدة التحكم (console) في متصفحكم.
• في محرر ONLYOFFICE، انتقلوا إلى علامة تبويب الاضافات وقوموا بتشغيل اضافتكم.

ملاحظة: سيعمل أمر debugger فقط إذا كانت أدوات المطور مفتوحة؛ وإلا سيتم تجاهله. يمكنكم قراءة المزيد حول ذلك في هذه الصفحة.

تصحيح أخطاء الاضافات في محررات الحاسوب

لتصحيح أخطاء الاضافات في إصدار الحاسوب لمحرر ONLYOFFICE، استخدموا النهج التالي:

• قوموا بتشغيل المحرر باستخدام العلامة –ascdesktop-support-debug-info.

• تتيح هذه العلامة عرض معلومات إضافية مفيدة لتصحيح الأخطاء.
• على غرار محررات الويب، أدخِلوا debugger; في الموقع المطلوب في الكود الخاص بكم.

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

• اضغطوا على F1 لفتح وحدة التحكم وتشغيل الاضافة.

بعد بدء تشغيل المحرر بالعلامة المحددة، افتحوا الاضافة وتتبعوا تنفيذ الكود.

تتوفر تعليمات مفصلة لأنظمة التشغيل المختلفة هنا.

إدارة النطاقات (Scopes)

عند تطوير اضافة ONLYOFFICE، من المهم فهم كيفية تمرير البيانات بين واجهة مستخدم الاضافة الخاصة بكم (صفحة HTML) وبيئة تنفيذ المحرر حيث يتم تشغيل أوامر Document Builder API. هذه سياقات أو نطاقات مختلفة.

أحد المصادر الشائعة للأخطاء هو التعامل غير السليم مع البيانات بين هذه النطاقات. يوفر ONLYOFFICE الكائن Asc.scope لتسهيل ذلك. يمكنكم إرفاق متغيرات بـ Asc.scope في النص البرمجي الرئيسي للاضافة الخاصة بكم، وستكون متاحة داخل الوظيفة التي تم تمريرها إلى this.callCommand().

إليكم مثال على كيفية تمرير متغير نصي إلى الاضافة الخاصة بكم إلى المحرر:

(function (window, undefined) {
    window.Asc.plugin.init = function () {
    // In your main script (e.g., scripts/plugin.js)
    let text = "Hello from the plugin!";
    Asc.scope.dataForEditor = text; // Export variable to the shared plugin scope
    // In the command executed in the editor's scope
    this.callCommand(function () {
         debugger;
         let oDocument = Api.GetDocument();
         let Paragraph = Api.CreateParagraph();
         oParagraph.AddText(Asc.scope.dataForEditor);// Access the variable via Asc.scope
         oDocument.InsertContent([oParagraph]);
    }, true);
  };
})(window, undefined);

يضمن الاستخدام السليم لـ Asc.scope تمرير البيانات بشكل صحيح بين السياقات المختلفة، وهو أمر بالغ الأهمية لبناء اضافات معقدة.

المشكلات الشائعة واستكشاف الأخطاء وإصلاحها

أثناء تصحيح الأخطاء، قد تواجهون العديد من المشكلات الشائعة. إليكم بعض المشكلات الأكثر تكراراً وحلولها:

عبارة Debugger لا تعمل

يتم تجاهل عبارة debugger; ولا يتوقف التنفيذ.

• تأكدوا من أن أدوات مطوري المتصفح (F12) مفتوحة قبل تشغيل الاضافة.
• تعمل عبارة debugger; فقط عندما تكون DevTools نشطة.

الاضافة لا يتم تحميلها أو غير مرئية

• تحققوا من أن ملف config.json منسق بشكل صحيح (JSON صالح).
• تحققوا من وجود جميع الحقول المطلوبة في config.json (الاسم، المعرف الفريد guid، وعنوان URL الأساسي baseUrl).
• افحصوا وحدة تحكم المتصفح بحثاً عن أي أخطاء في التحميل.
• تأكدوا من تثبيت الاضافة بشكل صحيح في علامة تبويب اضافات ONLYOFFICE.
• التثبيت اليدوي باستخدام ملف .plugin مضغوط أو طريقة Asc.editor.installDeveloperPlugin().

أخطاء Cors (مشاركة الموارد عبر الأصل)

• قوموا بتثبيت ONLYOFFICE Docs.
• بالنسبة لمحررات الويب في ONLYOFFICE Docs، تأكدوا من تشغيل http-server داخل مجلد الاضافة الخاص بكم.
• أو قوموا بضبط المسار لملف config.json الخاص بكم في installDeveloperPlugin().

Asc.editor.installDeveloperPlugin("https://<documentserver>:<port>/<folder-name>/config.json")

تم تغيير الملفات، الكود القديم لا يزال يعمل – محررات الويب

• إذا قمتم بتغيير الملفات المحلية للاضافة الخاصة بكم، ستحتاجون إلى تحديث صفحتكم وذاكرة التخزين المؤقت.
• انقروا بزر الماوس الأيمن على زر التحديث في متصفحكم واختاروا “Empty Cache and Hard Reload”، ثم شغلوا الاضافة مرة أخرى.

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

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