تتسبّب مشغّلات Apps Script في تنفيذ دالة نص برمجي محدّدة (دالة المشغّل) كلما وقع حدث محدّد. يمكن أن تؤدي أحداث معيّنة فقط إلى تشغيل المشغّلات، ويتوافق كل تطبيق من تطبيقات Google Workspace مع مجموعة مختلفة من الأحداث.
عندما يتم تشغيل مشغّل، يتم إنشاء عنصر حدث. يحتوي بنية JSON هذه على تفاصيل حول الحدث الذي وقع. يتم تنظيم المعلومات في بنية عنصر الحدث بشكل مختلف استنادًا إلى نوع المشغّل.
بعد إنشاء عنصر الحدث، تمرّره "برمجة تطبيقات Google" كمعلَمة إلى دالة المشغّل. دالة المشغّل هي دالة رد اتصال يجب تنفيذها بنفسك لاتّخاذ الإجراءات المناسبة للردّ على الحدث. على سبيل المثال، في إضافة Google Workspace التي توسّع نطاق Gmail، يمكنك تحديد مشغّل ينشئ واجهة بطاقة جديدة عندما يفتح المستخدم سلسلة محادثات. في هذه الحالة، عليك تنفيذ دالة ردّ اتصال سياقية لإنشاء البطاقات التي تشكّل واجهة المستخدم الجديدة باستخدام البيانات التي تم تمريرها في عنصر الحدث.
تقدّم هذه الصفحة إرشادات حول استخدام المشغّلات في مشاريع إضافات Google Workspace.
مشغّلات البيان
على عكس إضافات المحرّر، لا يمكن حاليًا لإضافات Google Workspace استخدام المشغّلات البسيطة في "برمجة التطبيقات". بدلاً من ذلك، تستخدم هذه الإضافات مشغّلات مصمَّمة خصيصًا لها، وهي مشغّلات ملف البيان.
يتم تحديد مشغّلات ملف البيان بالكامل في ملف البيان الخاص بإضافة Google Workspace. تشمل أمثلة مشغّلات ملف البيان ما يلي:
- مشغّلات الصفحة الرئيسية التي تنشئ وتعرض الصفحة الرئيسية للإضافة
- مشغّلات فتح حدث في التقويم التي تعرض بطاقة جديدة أو تتّخذ إجراءات أخرى عند فتح حدث في التقويم
- مشغّلات Calendar eventUpdate التي تعرض بطاقة جديدة أو تتّخذ إجراءات أخرى عندما يعدّل المستخدم حدثًا في "تقويم Google" ويحفظه
- العوامل المُشغِّلة onItemsSelected في Drive التي تعرض بطاقة جديدة أو تتّخذ إجراءات أخرى عندما يختار المستخدم ملفًا واحدًا أو أكثر أو مجلدات في Drive
- مشغّلات الإنشاء في Gmail التي تعرض بطاقة إضافة عندما يفتح المستخدم الإضافة في نافذة الإنشاء في Gmail
- المشغّلات السياقية في Gmail التي تعرض بطاقة جديدة أو تتّخذ إجراءات أخرى عندما يفتح المستخدم رسالة Gmail
- مشغّلات Editor onFileScopeGranted التي تعرض بطاقة جديدة عندما يمنح المستخدمون إذنًا لنطاق
drive.fileOAuth في مستند "المحرّر" الحالي.
في القائمة أعلاه، تكون مشغّلات الصفحة الرئيسية فقط غير سياقية، أما البقية فتكون مشغّلات سياقية. يمكنك الاطّلاع على ملف البيان للحصول على مزيد من المعلومات حول تعريفات مشغّلات ملف البيان.
بالإضافة إلى مشغّلات ملف البيان، يمكن أن تستخدم إضافات Google Workspace أيضًا المشغّلات القابلة للتثبيت في Apps Script.
القيود
تخضع مشغّلات البيان لقيود معيّنة على استخدامها.
- لا تُستخدَم هذه المشغّلات إلا في مشاريع إضافات Google Workspace، وليس لها أي غرض في أي تطبيق آخر.
- بما أنّ هذه المشغّلات معرَّفة في بيان الإضافة وليس في رمزها، لا يمكنك استخدام خدمة
Scriptفي "برمجة تطبيقات Google" لإنشاء هذه المشغّلات أو تعديلها. - يمكن أن تحتوي مشغِّلات Gmail السياقية حاليًا على معيار
unconditionalفقط. وهذا يعني أنّ المشغّلات السياقية يتم تفعيلها لكل رسالة إلكترونية، بغض النظر عن المحتوى. - يمكن أن تتضمّن كل إضافة مشغّلاً واحدًا فقط من كل نوع، لكل مستخدم، ولكل مستند.