محرک های ساده

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

شروع کردن

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

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

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

محدودیت ها

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

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

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

onOpen(e)

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

/**
 * 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)

هنگامی که کاربر یک افزونه ویرایشگر را از داخل سندنگار، کاربرگ‌نگار، اسلاید یا فرم‌های Google نصب می‌کند، راه‌انداز onInstall(e) به‌طور خودکار اجرا می‌شود. وقتی کاربر افزونه را از وب‌سایت Google Workspace Marketplace نصب می‌کند، ماشه اجرا نمی‌شود. توجه داشته باشید که محدودیت‌های خاصی در مورد آنچه onInstall(e) می‌تواند انجام دهد وجود دارد، درباره مجوز بیشتر بدانید. رایج ترین استفاده از onInstall(e) صرفاً فراخوانی onOpen(e) برای افزودن منوهای سفارشی است. از این گذشته، هنگامی که یک افزونه نصب می شود، فایل از قبل باز است، و بنابراین onOpen(e) به تنهایی اجرا نمی شود مگر اینکه فایل دوباره باز شود.

/**
 * 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) زیر نظری را روی سلول تنظیم می کند که آخرین باری که ویرایش شده را ثبت می کند.

/**
 * 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());
}

onSelectionChange(e)

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

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

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

/**
 * 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)

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

انواع محرک های موجود

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

رویداد	محرک های ساده	ماشه های قابل نصب
باز کنید	function onOpen(e)
ویرایش کنید	function onEdit(e)
تغییر انتخاب	function onSelectionChange(e)
نصب کنید	function onInstall(e)
تغییر دهید
فرم ارسال کنید
زمان محور (ساعت)
دریافت کنید	function doGet(e)
ارسال کنید	function doPost(e)

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