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

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

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

مربّعات حوار

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

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

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

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

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

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

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

الأشرطة الجانبية

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

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

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

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

   يبلغ عرض الأشرطة الجانبية للإضافات 300 بكسل، ولا يمكنك تغييره من خلال استدعاء HtmlOutput.setWidth.

3. اتّصِل بالرقم Ui.showSidebar لعرض الشريط الجانبي باستخدام HtmlOutput.

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