محرک های ساده (original) (raw)

تریگرها به 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 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 استفاده می‌شود.

onInstall(e)

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

onEdit(e)

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

onSelectionChange(e)

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

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

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

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)

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