عوامل تشغيل إضافات Google Workspace
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتسبّب مشغّلات 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.file OAuth في مستند "المحرّر" الحالي.
في القائمة أعلاه، تكون مشغّلات الصفحة الرئيسية فقط غير سياقية، أما البقية فتكون مشغّلات سياقية. يمكنك الاطّلاع على ملف البيان
للحصول على مزيد من المعلومات حول تعريفات مشغّلات ملف البيان.
بالإضافة إلى مشغّلات ملف البيان، يمكن أن تستخدم إضافات Google Workspace أيضًا المشغّلات القابلة للتثبيت في Apps Script.
القيود
تخضع مشغّلات البيان لقيود معيّنة على استخدامها.
- لا تُستخدَم هذه المشغّلات إلا في مشاريع إضافات Google Workspace، وليس لها أي غرض في أي تطبيق آخر.
- بما أنّ هذه المشغّلات معرَّفة في بيان الإضافة وليس في رمزها، لا يمكنك استخدام خدمة
Script في "برمجة تطبيقات Google" لإنشاء هذه المشغّلات أو تعديلها.
- يمكن أن تحتوي مشغِّلات Gmail السياقية حاليًا على معيار
unconditional فقط.
وهذا يعني أنّ المشغّلات السياقية يتم تفعيلها لكل رسالة إلكترونية، بغض النظر عن المحتوى.
- يمكن أن تتضمّن كل إضافة مشغّلاً واحدًا فقط من كل نوع، لكل مستخدم، ولكل مستند.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-07-31 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eApps Script triggers execute a specific function when a defined event occurs within a Google Workspace application.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Workspace add-ons utilize manifest triggers, defined in the add-on's manifest, to respond to events like opening a document or composing an email.\u003c/p\u003e\n"],["\u003cp\u003eManifest triggers can be contextual, reacting to specific user actions within a document or application, or non-contextual, like those that build the add-on's homepage.\u003c/p\u003e\n"],["\u003cp\u003eWhile manifest triggers offer event-driven functionality, they have limitations, including restrictions on their use and creation methods.\u003c/p\u003e\n"]]],["Apps Script triggers initiate a script function when specific events occur, creating an event object with event details. This object is then passed to a user-implemented trigger function, enabling actions based on the event. Google Workspace add-ons use manifest triggers, defined in the add-on's manifest, to trigger actions like displaying cards on homepage, when opening/updating Calendar events, selecting Drive items, or opening a message in Gmail. Contextual triggers and installable triggers are also supported but with some restrictions.\n"],null,["# Triggers for Google Workspace add-ons\n\n[Apps Script triggers](/apps-script/guides/triggers) cause a specified script\nfunction (the *trigger function*) to execute whenever a specified event\noccurs. Only certain events can cause triggers to fire, and each\nGoogle Workspace application supports a different set of events.\n\nWhen a trigger fires, an *event object* is created. This JSON structure\ncontains details about the event that occurred. The information in the event\nobject structure is organized differently based on the trigger type.\n\nOnce the event object is created, Apps Script passes it as a parameter to the\ntrigger function. The trigger function is a callback function that you must\nimplement yourself, to take whatever actions are appropriate to respond to the\nevent. For example, in a\nGoogle Workspace add-on that extends Gmail, you can\ndefine a trigger that creates a new card interface when the user opens a message\nthread. In this case, you implement a contextual callback function to create\nthe cards making up the new UI using the data passed in the\n[event object](/workspace/add-ons/concepts/event-objects).\n\nThis page provides guidelines on using triggers in\nGoogle Workspace\nadd-on projects.\n\nManifest triggers\n-----------------\n\nUnlike Editor add-ons, Google Workspace add-ons\ncurrently can't use Apps Script [simple triggers](/apps-script/guides/triggers)\nInstead, they use triggers designed specifically for\nGoogle Workspace add-ons: *manifest triggers*.\n\nManifest triggers are defined completely in the\nGoogle Workspace add-on's\n[manifest](/workspace/add-ons/concepts/workspace-manifests). Examples of manifest triggers include the\nfollowing:\n\n- **Homepage triggers** that build and display the add-on homepage.\n- **Calendar eventOpen triggers** that display a new card or take other actions when a Calendar event is opened.\n- **Calendar eventUpdate triggers** that display a new card or take other actions when a user edits and saves a Calendar event.\n- **Drive onItemsSelected triggers** that display a new card or take other actions when a user selects one or more files or folders in Drive.\n- **Gmail compose triggers** that display an add-on card when the user opens the add-on in the Gmail compose window.\n- **Gmail contextual triggers** that display a new card or take other actions when the user opens a Gmail message.\n- **Editor onFileScopeGranted triggers** that display a new card when users grant authorization for the `drive.file` OAuth scope in the current Editor document.\n\nIn the above list, only homepage triggers are non-contextual; the rest are\ncontextual triggers. See [Manifest](/workspace/add-ons/concepts/workspace-manifests)\nfor more information about manifest trigger definitions.\n\nIn addition to manifest triggers, Google Workspace\nadd-ons can also use Apps Script\n[installable triggers](/apps-script/guides/triggers/installable).\n\n### Restrictions\n\nManifest triggers have certain restrictions to their use.\n\n- These triggers are only used in Google Workspace add-on projects; they have no purpose in any other application.\n- Since they are defined in the add-on manifest and not in its code, you can't use the Apps Script [`Script`](/apps-script/reference/script) service to create or modify these triggers.\n- Gmail contextual triggers currently can only have an `unconditional` criteria. This means contextual triggers fire for every email message, regardless of content.\n- Each add-on can only have one trigger of each type, per user, per document."]]
