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

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

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

مربّعات حوار

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

يمكنك إنشاء مربّعات حوار الإضافات بالطريقة نفسها التي تنشئ بها مربّعات الحوار المخصّصة في "برمجة تطبيقات Google"، والإجراء العام المقترَح هو كما يلي:

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

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

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

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

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

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

يمكنك إنشاء أشرطة جانبية للإضافات بالطريقة نفسها التي تنشئ بها الأشرطة الجانبية المخصّصة في "برمجة تطبيقات Google"، والإجراء العام المقترَح هو كما يلي:

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

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

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

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