محرک های ساده

تریگرها به Google Apps Script اجازه می‌دهند تا هنگام وقوع یک رویداد خاص، مانند باز کردن یک سند، یک تابع را به طور خودکار اجرا کند. تریگرهای ساده مجموعه‌ای از توابع رزرو شده هستند که در Apps Script تعبیه شده‌اند، مانند تابع onOpen(e) که هنگام باز کردن یک فایل Google Docs، Sheets، Slides یا Forms توسط کاربر اجرا می‌شوند. تریگرهای قابل نصب قابلیت‌های بیشتری نسبت به تریگرهای ساده ارائه می‌دهند، اما قبل از استفاده باید فعال شوند. برای هر دو نوع تریگر، Apps Script یک شیء رویداد را به تابع تریگر شده ارسال می‌کند که حاوی اطلاعاتی در مورد زمینه‌ای است که رویداد در آن رخ داده است.

برای اطلاعات بیشتر در مورد نحوه استفاده از محرک‌ها در پروژه‌های افزونه Google Workspace، به بخش محرک‌ها برای افزونه‌های Google Workspace مراجعه کنید.

شروع به کار

برای استفاده از یک تریگر ساده، تابعی ایجاد کنید که از یکی از این نام‌های رزرو شده برای توابع استفاده کند:

  • onOpen(e) زمانی اجرا می‌شود که کاربر یک صفحه گسترده، سند، ارائه یا فرمی را که مجوز ویرایش آن را دارد، باز می‌کند.
  • onInstall(e) زمانی اجرا می‌شود که کاربر یک افزونه ویرایشگر را از داخل Google Docs، Sheets، Slides یا Forms نصب کند.
  • onEdit(e) زمانی اجرا می‌شود که کاربر مقداری را در یک صفحه گسترده تغییر دهد.
  • onSelectionChange(e) زمانی اجرا می‌شود که کاربر انتخاب را در یک صفحه گسترده تغییر دهد.
  • doGet(e) زمانی اجرا می‌شود که کاربری از یک برنامه وب بازدید می‌کند یا برنامه‌ای یک درخواست HTTP GET به یک برنامه وب ارسال می‌کند.
  • doPost(e) زمانی اجرا می‌شود که یک برنامه یک درخواست HTTP POST را به یک برنامه وب ارسال کند.

پارامتر e در نام توابع بالا یک شیء رویداد است که به تابع ارسال می‌شود. این شیء حاوی اطلاعاتی در مورد زمینه‌ای است که باعث فعال شدن تریگر شده است، اما استفاده از آن اختیاری است.

محدودیت‌ها

از آنجا که تریگرهای ساده به طور خودکار و بدون درخواست مجوز از کاربر فعال می‌شوند، مشمول چندین محدودیت هستند:

  • این اسکریپت باید به یک فایل Google Sheets، Slides، Docs یا Forms متصل باشد، یا افزونه‌ای باشد که یکی از آن برنامه‌ها را گسترش می‌دهد.
  • اگر فایلی در حالت فقط خواندنی (مشاهده یا نظر دادن) باز باشد، اجرا نمی‌شوند.
  • اجرای اسکریپت‌ها و درخواست‌های API باعث اجرای triggerها نمی‌شوند. برای مثال، فراخوانی Range.setValue() برای ویرایش یک سلول باعث اجرای trigger مربوط onEdit صفحه گسترده نمی‌شود.
  • آنها نمی‌توانند به سرویس‌هایی که نیاز به مجوز دارند دسترسی داشته باشند. برای مثال، یک تریگر ساده نمی‌تواند ایمیل ارسال کند زیرا سرویس Gmail نیاز به مجوز دارد، اما یک تریگر ساده می‌تواند عبارتی را با سرویس زبان ترجمه کند که ناشناس است.
  • آنها می‌توانند فایلی را که به آن متصل هستند تغییر دهند، اما نمی‌توانند به فایل‌های دیگر دسترسی پیدا کنند زیرا این کار نیاز به مجوز دارد.
  • بسته به مجموعه‌ای پیچیده از محدودیت‌های امنیتی ، آنها ممکن است بتوانند هویت کاربر فعلی را تعیین کنند یا نتوانند.
  • آنها نمی‌توانند بیش از 30 ثانیه بدوند.
  • در شرایط خاص، افزونه‌های ویرایشگر، محرک‌های ساده‌ی onOpen(e) و onEdit(e) خود را در حالت بدون مجوز اجرا می‌کنند که پیچیدگی‌های بیشتری را ایجاد می‌کند. برای اطلاعات بیشتر، به راهنمای چرخه‌ی مجوز افزونه مراجعه کنید.
  • تریگرهای ساده مشمول محدودیت‌های سهمیه تریگر Apps Script هستند.

این محدودیت‌ها شامل doGet(e) یا doPost(e) نمی‌شوند.

onOpen(e)

تریگر onOpen(e) به طور خودکار زمانی اجرا می‌شود که کاربر یک صفحه گسترده، سند، ارائه یا فرمی را که اجازه ویرایش آن را دارد، باز می‌کند. (تریگر هنگام پاسخ دادن به یک فرم اجرا نمی‌شود، فقط هنگام باز کردن فرم برای ویرایش آن اجرا می‌شود.) onOpen(e) معمولاً برای اضافه کردن آیتم‌های منوی سفارشی به Google Sheets، Slides، Docs یا Forms استفاده می‌شود.

triggers/triggers.gs
/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
    .createMenu("Custom Menu")
    .addItem("First item", "menuItem1")
    .addToUi();
}

onInstall(e)

تریگر onInstall(e) به طور خودکار زمانی اجرا می‌شود که کاربر یک افزونه ویرایشگر را از داخل Google Docs، Sheets، Slides یا Forms نصب کند. این تریگر زمانی اجرا نمی‌شود که کاربر افزونه را از وب‌سایت Google Workspace Marketplace نصب کند. رایج‌ترین کاربرد onInstall(e) فراخوانی onOpen(e) برای افزودن منوهای سفارشی است. پس از نصب یک افزونه، فایل از قبل باز است و بنابراین onOpen(e) به خودی خود اجرا نمی‌شود مگر اینکه فایل دوباره باز شود. توجه داشته باشید که محدودیت‌های خاصی در مورد کارهایی که onInstall(e) می‌تواند انجام دهد وجود دارد. درباره مجوز بیشتر بدانید.

triggers/triggers.gs
/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

تریگر onEdit(e) به طور خودکار زمانی اجرا می‌شود که کاربر مقدار هر سلولی را در صفحه گسترده تغییر دهد. اکثر تریگرهای onEdit(e) از اطلاعات موجود در شیء رویداد برای پاسخ مناسب استفاده می‌کنند. به عنوان مثال، تابع onEdit(e) در زیر، یک نظر (کامنت) روی سلولی که آخرین بار ویرایش شده است، ثبت می‌کند.

triggers/triggers.gs
/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote(`Last modified: ${new Date()}`);
}

onEdit() فقط تا ۲ رویداد تریگر را در صف قرار می‌دهد.

onSelectionChange(e)

تریگر onSelectionChange(e) به طور خودکار زمانی اجرا می‌شود که کاربر انتخاب را در یک صفحه گسترده تغییر دهد. برای فعال کردن این تریگر، پس از اضافه شدن تریگر و هر بار که صفحه گسترده باز می‌شود، صفحه گسترده را رفرش کنید.

اگر انتخاب در مدت زمان کوتاهی بین چندین سلول جابجا شود، ممکن است برخی از رویدادهای تغییر انتخاب برای کاهش تأخیر نادیده گرفته شوند. برای مثال، اگر تغییرات انتخاب زیادی در فاصله دو ثانیه از یکدیگر انجام شوند، فقط اولین و آخرین تغییرات انتخاب، تریگر onSelectionChange(e) را فعال می‌کنند.

در مثال زیر، اگر یک سلول خالی انتخاب شود، تابع onSelectionChange(e) پس‌زمینه سلول را به رنگ قرمز تنظیم می‌کند.

triggers/triggers.gs
/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (
    range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === ""
  ) {
    range.setBackground("red");
  }
}

doGet(e) و doPost(e)

تریگر doGet(e) به طور خودکار زمانی اجرا می‌شود که کاربر از یک برنامه وب بازدید می‌کند یا برنامه‌ای یک درخواست HTTP GET به یک برنامه وب ارسال می‌کند. doPost(e) زمانی اجرا می‌شود که یک برنامه یک درخواست HTTP POST به یک برنامه وب ارسال می‌کند. این تریگرها در راهنماهای برنامه‌های وب ، سرویس HTML و سرویس محتوا بیشتر نشان داده شده‌اند. توجه داشته باشید که doGet(e) و doPost(e) مشمول محدودیت‌های ذکر شده در بالا نیستند.

انواع تریگرهای موجود

اگر محدودیت‌های مربوط به تریگرهای ساده مانع از برآورده شدن نیازهای شما می‌شود، یک تریگر قابل نصب می‌تواند به جای آن کارساز باشد. جدول زیر خلاصه‌ای از انواع تریگرهای موجود برای هر نوع رویداد را نشان می‌دهد. به عنوان مثال، Google Sheets، Slides، Forms و Docs همگی از تریگرهای باز ساده پشتیبانی می‌کنند، اما فقط Sheets، Docs و Forms از تریگرهای باز قابل نصب پشتیبانی می‌کنند.

رویداد محرک‌های ساده تریگرهای قابل نصب
باز
ورق‌ها
اسلایدها
فرم‌ها*
اسناد

function onOpen(e)

ورق‌ها
فرم‌ها*
اسناد
ویرایش
ورق‌ها

function onEdit(e)

ورق‌ها
تغییر انتخاب
ورق‌ها

function onSelectionChange(e)

نصب
ورق‌ها
اسلایدها
فرم‌ها
اسناد

function onInstall(e)

تغییر
ورق‌ها
ارسال فرم
ورق‌ها
فرم‌ها
زمان‌محور (ساعت)
ورق‌ها
اسلایدها
فرم‌ها
اسناد
مستقل
دریافت
مستقل

function doGet(e)

پست
مستقل

function doPost(e)

* رویداد باز کردن فرم‌های گوگل زمانی رخ نمی‌دهد که کاربر فرمی را برای پاسخ دادن باز می‌کند، بلکه زمانی رخ می‌دهد که ویرایشگر فرم را برای تغییر آن باز می‌کند.