مربّعات الحوار والأشرطة الجانبية في "إضافة المحرّر"

في معظم الإضافات للمحرّر، تشكل نوافذ الحوار ولوحات الشريط الجانبي واجهات المستخدم الأساسية للإضافة. يمكن تخصيص كليهما بالكامل باستخدام HTML وCSS العاديَين، ويمكنك استخدام نموذج تواصل العميل والخادم في Apps Script لتشغيل دوال Apps Script عندما يتفاعل المستخدم مع الشريط الجانبي أو مربّع الحوار. يمكن أن تحدِّد الإضافة نوافذ جانبية ومربّعات حوار متعددة، ولكن يمكن أن تعرِض الإضافة واحدة فقط في كل مرة.

إذا كنت تريد منع المستخدم من التفاعل مع المحرِّر إلى أن يصعِد ويحدد خيارًا في واجهة الإضافة، استخدِم مربّع حوار، وإلا استخدِم جانبًا.

مربّعات حوار

مربّعات الحوار هي أقسام في النوافذ تُظهر فوق محتوى المحرّر الأساسي. حوارات Apps Script هي مشروطة، ولا يمكن للمستخدم التفاعل مع العناصر الأخرى في واجهة المحرِّر أثناء فتحها. يمكنك تخصيص محتوى الحوارات وحجمها.

يمكنك إنشاء مربّعات حوار الإضافات بالطريقة نفسها التي يتم بها إنشاء مربّعات الحوار المخصّصة في Apps Script. في ما يلي الإجراء العام المُقترَح:

  1. أنشئ ملف مشروع نص برمجي يحدّد بنية HTML و CSS وسلوك JavaScript من جهة العميل في مربّع الحوار. عند تحديد مربّع الحوار، يُرجى الرجوع إلى إرشادات أسلوب إضافة المحرّر.
  2. في الرمز البرمجي من جهة الخادم حيث تريد فتح مربّع الحوار، استخدِم دالة HtmlService.createHtmlOutputFromFile(filename) لإنشاء عنصر HtmlOutput يمثّل مربّع الحوار. بدلاً من ذلك، إذا كنت تستخدم HTML المستند إلى النماذج، يمكنك استدعاء HtmlService.createTemplateFromFile(filename) لإنشاء نموذج ثم HtmlTemplate.evaluate() لتحويله إلى عنصر HtmlOutput.
  3. اتصل بالرقم Ui.showModalDialog(htmlOutput, dialogTitle) لعرض مربّع الحوار باستخدام HtmlOutput.

لا تعلّق مربّعات الحوار النصوص البرمجية من جهة الخادم عندما تكون مفتوحة. يمكن لـ JavaScript من جهة العميل إجراء مكالمات غير متزامنة من جهة الخادم باستخدام google.script.run() و وظائف المعالج المرتبطة. لمزيد من التفاصيل، يُرجى الاطّلاع على التواصل بين العميل والخادم.

مربّعات حوار فتح الملفات

مربّعات حوار فتح الملفات هي مربّعات حوار مُنشأة مسبقًا تتيح للمستخدمين اختيار الملفات من Google Drive. يمكنك إضافة مربّع حوار لفتح الملفات إلى الإضافة بدون الحاجة إلى تصميمه، ولكنّ ذلك يتطلّب بعض الإعدادات الإضافية. يجب أيضًا الحصول على إذن بالوصول إلى مشروع Cloud Platform للإضافة من أجل تفعيل Google Picker API.

لمعرفة التفاصيل الكاملة، يُرجى الاطّلاع على مربّعات الحوار لفتح الملفات.

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

يمكنك إنشاء أشرطة جانبية إضافية بالطريقة نفسها التي يتم بها إنشاء أشرطة جانبية مخصّصة في Apps Script. في ما يلي الإجراء العام المُقترَح:

  1. أنشئ ملف مشروع نص برمجي يحدّد بنية HTML و CSS وسلوك JavaScript من جهة العميل في الشريط الجانبي. عند تحديد الشريط الجانبي، يُرجى الرجوع إلى إرشادات نمط إضافات المحرِّر.

  2. في الرمز البرمجي من جهة الخادم حيث تريد فتح الشريط الجانبي، استخدِم HtmlService.createHtmlOutputFromFile(filename) لإنشاء عنصر HtmlOutput يمثّل الشريط الجانبي. بدلاً من ذلك، إذا كنت تستخدم HTML المستند إلى النماذج، يمكنك استدعاء HtmlService.createTemplateFromFile(filename) لإنشاء نموذج ثم HtmlTemplate.evaluate() لتحويله إلى عنصر HtmlOutput.

  3. استخدِم Ui.showSidebar(htmlOutput) لعرض الشريط الجانبي باستخدام HtmlOutput.

لا تعلّق الأشرطة الجانبية النصوص البرمجية من جهة الخادم عندما تكون مفتوحة. يمكن لـ JavaScript من جهة العميل إجراء مكالمات غير متزامنة من جهة الخادم باستخدام google.script.run() و وظائف المعالج المرتبطة. لمزيد من التفاصيل، يُرجى الاطّلاع على التواصل بين العميل والخادم.