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