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

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

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

مربّعات حوار

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

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

  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.

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

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

يتم إنشاء أشرطة جانبية للإضافات بالطريقة نفسها التي تصمم بها الأشرطة الجانبية المخصصة لبرمجة التطبيقات، ويتمثّل الإجراء العام الموصى به في ما يلي:

  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() ودوال المعالج المرتبطة بها. للحصول على مزيد من التفاصيل، راجع الاتصال من عميل إلى خادم.