محرک‌های افزونه‌های Google Workspace
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
راه‌اندازهای Apps Script باعث می‌شوند تا هر زمان که یک رویداد مشخص رخ می‌دهد، یک تابع اسکریپت مشخص ( عملکرد ماشه ) اجرا شود. فقط رویدادهای خاصی می‌توانند باعث فعال شدن محرک‌ها شوند و هر برنامه Google Workspace مجموعه متفاوتی از رویدادها را پشتیبانی می‌کند.
هنگامی که یک ماشه فعال می شود، یک شی رویداد ایجاد می شود. این ساختار JSON حاوی جزئیات مربوط به رویدادی است که رخ داده است. اطلاعات در ساختار شی رویداد بر اساس نوع ماشه سازماندهی متفاوتی دارد.
پس از ایجاد شی رویداد، Apps Script آن را به عنوان پارامتر به تابع ماشه ارسال می کند. تابع ماشه یک تابع تماس است که باید خودتان آن را پیاده سازی کنید تا هر اقدامی را که برای پاسخ به رویداد مناسب است انجام دهید. به عنوان مثال، در یک افزونه Google Workspace که Gmail را گسترش می‌دهد، می‌توانید یک ماشه تعریف کنید که وقتی کاربر یک رشته پیام را باز می‌کند، یک رابط کارت جدید ایجاد می‌کند. در این مورد، یک تابع فراخوان متنی را برای ایجاد کارت هایی که رابط کاربری جدید را با استفاده از داده های ارسال شده در شی رویداد ایجاد می کنند، پیاده سازی می کنید.
این صفحه دستورالعمل‌هایی درباره استفاده از محرک‌ها در پروژه‌های الحاقی Google Workspace ارائه می‌کند.
محرک های آشکار
بر خلاف افزونه‌های ویرایشگر، افزونه‌های Google Workspace در حال حاضر نمی‌توانند از محرک‌های ساده Apps Script استفاده کنند، در عوض، از محرک‌هایی استفاده می‌کنند که به‌طور خاص برای افزونه‌های Google Workspace طراحی شده‌اند: محرک‌های مانیفست .
محرک های مانیفست به طور کامل در مانیفست افزونه Google Workspace تعریف شده اند. نمونه هایی از محرک های مانیفست شامل موارد زیر است:
- صفحه اصلی باعث ایجاد و نمایش صفحه اصلی افزونه می شود.
- Calendar eventOpen راه‌اندازی می‌کند که یک کارت جدید را نمایش می‌دهد یا وقتی یک رویداد تقویم باز می‌شود، اقدامات دیگری انجام می‌دهد.
- Calendar eventUpdate راه‌اندازی می‌کند که یک کارت جدید را نمایش می‌دهد یا زمانی که کاربر یک رویداد تقویم را ویرایش و ذخیره می‌کند، اقدامات دیگری انجام می‌دهد.
- درایو onItemsSelected محرک هایی است که وقتی کاربر یک یا چند فایل یا پوشه را در Drive انتخاب می کند، کارت جدیدی را نمایش می دهد یا اقدامات دیگری انجام می دهد.
- راه‌اندازهای نوشتن Gmail که وقتی کاربر افزونه را در پنجره نوشتن Gmail باز می‌کند، یک کارت افزونه را نمایش می‌دهد.
- راه‌اندازهای متنی Gmail که یک کارت جدید را نمایش می‌دهند یا وقتی کاربر یک پیام Gmail را باز می‌کند، اقدامات دیگری انجام می‌دهد.
- Editor onFileScopeGranted راه‌اندازهایی را نشان می‌دهد که وقتی کاربران مجوزی برای حوزه
drive.file OAuth در سند ویرایشگر فعلی اعطا می‌کنند، کارت جدیدی را نمایش می‌دهند.
در لیست بالا، فقط محرک های صفحه اصلی غیر متنی هستند. بقیه محرک های زمینه ای هستند. برای اطلاعات بیشتر درباره تعاریف ماشه مانیفست، به Manifest مراجعه کنید.
افزونه‌های Google Workspace علاوه بر محرک‌های مانیفست، می‌توانند از محرک‌های قابل نصب Apps Script نیز استفاده کنند.
محدودیت ها
محرک های آشکار محدودیت های خاصی برای استفاده از آنها دارند.
- این محرک‌ها فقط در پروژه‌های الحاقی Google Workspace استفاده می‌شوند. آنها هیچ هدفی در هیچ برنامه دیگری ندارند.
- از آنجایی که آنها در مانیفست افزودنی تعریف شده‌اند و نه در کد آن، نمی‌توانید از سرویس Apps Script
Script برای ایجاد یا تغییر این محرک‌ها استفاده کنید. - راه‌اندازهای متنی Gmail در حال حاضر فقط می‌توانند یک معیار
unconditional داشته باشند. این بدان معناست که برای هر پیام ایمیل، صرف نظر از محتوا، محرک های متنی فعال می شوند. - هر افزونه فقط می‌تواند از هر نوع یک راه‌انداز، به ازای هر کاربر، در هر سند داشته باشد.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-07-30 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-07-30 بهوقت ساعت هماهنگ جهانی."],[[["\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."]]
