Triggers برای افزونه های ویرایشگر، Triggers برای افزونه های ویرایشگر، Triggers برای افزونه های ویرایشگر

تریگرهای اسکریپت برنامه‌ها باعث می‌شوند که یک تابع اسکریپت مشخص ( تابع تریگر ) هر زمان که یک رویداد مشخص رخ می‌دهد، اجرا شود. فقط رویدادهای خاصی می‌توانند باعث فعال شدن تریگرها شوند و هر برنامه Google Workspace از مجموعه متفاوتی از رویدادها پشتیبانی می‌کند.

وقتی یک trigger فعال می‌شود، یک شیء رویداد ایجاد می‌شود. این ساختار JSON شامل جزئیاتی در مورد رویدادی است که رخ داده است. اطلاعات موجود در ساختار شیء رویداد بر اساس نوع trigger به طور متفاوتی سازماندهی می‌شوند.

پس از ایجاد شیء رویداد، Apps Script آن را به عنوان پارامتر به تابع trigger ارسال می‌کند. تابع trigger یک تابع فراخوانی است که باید خودتان پیاده‌سازی کنید تا هر اقدام مناسب برای پاسخ به رویداد را انجام دهد. به عنوان مثال، در یک افزونه ویرایشگر، از یک trigger برای ایجاد آیتم‌های منوی افزونه هنگام باز شدن یک سند استفاده می‌شود. در این حالت، شما تابع trigger روی onOpen(e) را پیاده‌سازی می‌کنید تا آیتم‌های منوی مورد نیاز افزونه را ایجاد کند، احتمالاً با استفاده از داده‌های موجود در شیء رویداد.

این صفحه دستورالعمل‌هایی در مورد استفاده از تریگرها در پروژه‌های افزونه ویرایشگر ارائه می‌دهد.

انواع تریگر افزونه ویرایشگر

شما می‌توانید از اکثر انواع تریگرهای عمومی موجود در پروژه‌های Apps Script در افزونه‌های ویرایشگر، از جمله تریگرهای ساده و اکثر تریگرهای قابل نصب، استفاده کنید. مجموعه دقیق انواع تریگرهای موجود به برنامه‌ای که قرار است توسعه داده شود بستگی دارد.

توجه: برخلاف افزونه‌های ویرایشگر، افزونه‌های Google Workspace در حال حاضر نمی‌توانند از تریگرهای عمومی Apps Script ساده یا قابل نصب استفاده کنند. در عوض، آنها از تریگرهایی استفاده می‌کنند که مخصوص افزونه‌های Google Workspace طراحی شده‌اند. برای اطلاعات بیشتر، به تریگرهای افزونه‌های Google Workspace مراجعه کنید.

جدول زیر انواع تریگرهای ساده و قابل نصب را که افزونه‌های ویرایشگر می‌توانند استفاده کنند نشان می‌دهد و پیوندهایی به اشیاء رویداد مربوطه ارائه می‌دهد:

رویداد	شیء رویداد	محرک‌های ساده	تریگرهای قابل نصب
باز یک فایل ویرایشگر باز می‌شود.	اسناد شیء رویداد onOpen شیء رویداد Forms onOpen شیء رویداد Sheets onOpen اسلایدها روی شیء رویداد باز می‌شوند	اسناد فرم‌ها* ورق‌ها اسلایدها function onOpen(e)	اسناد فرم‌ها ورق‌ها
نصب افزونه نصب شده است.	شیء رویداد onInstall	اسناد فرم‌ها ورق‌ها اسلایدها function onInstall(e)
ویرایش محتوای سلول‌های صفحه گسترده تغییر می‌کند.	شیء رویداد Sheets onEdit	ورق‌ها function onEdit(e)	ورق‌ها
تغییر محتوای یک برگه ویرایش یا قالب‌بندی می‌شود.	شیء رویداد Sheets onChange		ورق‌ها
فرم-ارسال یک فرم گوگل ارسال می‌شود.	شیء رویداد ارسال فرم شیء رویداد فرم-ارسال برگه‌ها		فرم‌ها ورق‌ها
زمان‌محور (ساعت) ماشه در یک زمان یا فاصله زمانی مشخص فعال می‌شود.	شیء رویداد زمان‌محور		اسناد فرم‌ها ورق‌ها اسلایدها

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

محرک‌های ساده در افزونه‌ها

تریگرهای ساده از مجموعه‌ای از نام‌های تابع رزرو شده استفاده می‌کنند، نمی‌توانند از سرویس‌هایی که نیاز به مجوز دارند استفاده کنند و به طور خودکار برای استفاده فعال می‌شوند. در برخی موارد، یک رویداد تریگر ساده می‌تواند توسط یک تریگر قابل نصب مدیریت شود.

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

• onOpen(e) زمانی اجرا می‌شود که کاربر یک سند، صفحه گسترده یا ارائه را باز می‌کند. onOpen(e) همچنین می‌تواند زمانی که یک فرم در ویرایشگر باز می‌شود اجرا شود (اما نه هنگام پاسخ دادن به فرم). این تابع فقط در صورتی اجرا می‌شود که کاربر مجوز ویرایش فایل مورد نظر را داشته باشد و اغلب برای ایجاد آیتم‌های منو استفاده می‌شود.
• onInstall(e) زمانی اجرا می‌شود که کاربر یک افزونه را نصب کند. معمولاً onInstall(e) فقط برای فراخوانی تابع onOpen(e) استفاده می‌شود؛ این تابع تضمین می‌کند که منوهای افزونه بلافاصله پس از نصب و بدون نیاز به رفرش صفحه توسط کاربر، نمایش داده شوند.
• onEdit(e) زمانی اجرا می‌شود که کاربر مقدار یک سلول را در یک صفحه گسترده تغییر دهد. این تریگر در پاسخ به جابجایی سلول‌ها، قالب‌بندی یا سایر تغییراتی که مقادیر سلول را تغییر نمی‌دهند، فعال نمی‌شود.

محدودیت‌ها

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

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

تریگرهای قابل نصب در افزونه‌ها

افزونه‌ها می‌توانند به صورت برنامه‌نویسی‌شده با سرویس Script Apps Script تریگرهای قابل نصب را ایجاد و اصلاح کنند . تریگرهای قابل نصب افزونه را نمی‌توان به صورت دستی ایجاد کرد. برخلاف تریگرهای ساده، تریگرهای قابل نصب می‌توانند از سرویس‌هایی که نیاز به مجوز دارند استفاده کنند.

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

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

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

• تریگرهای قابل نصب با قابلیت ارسال فرم، زمانی اجرا می‌شوند که پاسخی از گوگل فرم ارسال شود.

  توجه: دو نسخه از تریگرهای ارسال فرم وجود دارد، یکی برای Sheets (که در آن پاسخ‌های فرم جمع‌آوری می‌شوند) و دیگری برای Google Forms. شیء رویدادی که به تابع تریگر ارسال فرم Sheets ارسال می‌شود، ساده‌تر است و مقادیر پاسخ را در آرایه‌های ساده برمی‌گرداند. شیء رویدادی که به تابع تریگر ارسال فرم Forms ارسال می‌شود ، اطلاعات بیشتری را ارائه می‌دهد که در یک شیء FormResponse قرار دارد.

• تریگرهای زمان‌محور (که تریگرهای ساعتی نیز نامیده می‌شوند) در یک زمان خاص یا به طور مکرر در یک بازه زمانی منظم فعال می‌شوند.

مجوزدهی تریگرهای قابل نصب

معمولاً اگر یک توسعه‌دهنده افزونه‌ای را برای استفاده از سرویس‌های جدیدی که نیاز به مجوز اضافی دارند، به‌روزرسانی کند، از کاربران خواسته می‌شود دفعه‌ی بعد که از افزونه استفاده می‌کنند، آن را دوباره مجاز کنند.

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

برخلاف تریگرها در پروژه‌های اسکریپت اپلیکیشن‌های معمولی، تریگرها در افزونه‌ها حتی اگر نیاز به مجوز مجدد داشته باشند، به فعال شدن ادامه می‌دهند. با این حال، اگر اسکریپت به خطی از کد برخورد کند که نیاز به مجوزی دارد که اسکریپت آن را ندارد، همچنان با شکست مواجه می‌شود. برای جلوگیری از این وضعیت، توسعه‌دهندگان می‌توانند از متد ScriptApp.getAuthorizationInfo() برای مسدود کردن دسترسی به بخش‌هایی از کد که بین نسخه‌های منتشر شده افزونه تغییر کرده‌اند، استفاده کنند.

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

کد.gs

triggers/form/Code.gs

مشاهده در گیت‌هاب

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = "My Add-on Title";
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (
    authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.REQUIRED
  ) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty("lastAuthEmailDate");
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile("AuthorizationEmail");
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(
          Session.getEffectiveUser().getEmail(),
          "Authorization Required",
          message.getContent(),
          {
            name: addonTitle,
            htmlBody: message.getContent(),
          },
        );
      }
      props.setProperty("lastAuthEmailDate", today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

ایمیل مجوز.html

triggers/form/AuthorizationEmail.html

مشاهده در گیت‌هاب

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

محدودیت‌ها

تریگرهای قابل نصب در افزونه‌ها مشمول همان محدودیت‌هایی هستند که تریگرهای قابل نصب در انواع دیگر پروژه‌های اسکریپت برنامه‌ها را کنترل می‌کنند.

علاوه بر این محدودیت‌ها، چندین محدودیت دیگر نیز به طور خاص برای تریگرهای قابل نصب در افزونه‌ها اعمال می‌شود:

• هر افزونه فقط می‌تواند یک تریگر از هر نوع، برای هر کاربر و برای هر سند، داشته باشد. برای مثال، در یک صفحه گسترده مشخص، یک کاربر مشخص فقط می‌تواند یک تریگر ویرایش داشته باشد، اگرچه کاربر می‌تواند یک تریگر ارسال فرم یا تریگر زمان‌محور نیز در همان صفحه گسترده داشته باشد. یک کاربر متفاوت با دسترسی به همان صفحه گسترده می‌تواند مجموعه تریگرهای جداگانه خود را داشته باشد.
• افزونه‌ها فقط می‌توانند برای فایلی که افزونه در آن استفاده شده است، تریگر ایجاد کنند. یعنی افزونه‌ای که در گوگل داک A استفاده می‌شود، نمی‌تواند تریگری برای نظارت بر باز شدن گوگل داک B ایجاد کند.
• تریگرهای زمان‌محور نمی‌توانند بیشتر از یک بار در ساعت اجرا شوند.
• افزونه‌ها وقتی کدی که توسط یک تریگر قابل نصب اجرا می‌شود، استثنا ایجاد می‌کند، به طور خودکار ایمیلی به کاربر ارسال نمی‌کنند. این وظیفه توسعه‌دهنده است که موارد خرابی را بررسی و به درستی مدیریت کند.
• محرک‌های افزونه در هر یک از شرایط زیر متوقف می‌شوند:
  • اگر افزونه توسط کاربر حذف نصب شود،
  • اگر افزونه در سندی غیرفعال شده باشد (اگر دوباره فعال شود، ماشه دوباره فعال می‌شود)، یا
  • اگر توسعه‌دهنده افزونه را از حالت انتشار خارج کند یا یک نسخه ناقص را به فروشگاه افزونه‌ها ارسال کند.
• توابع تریگر افزونه تا زمانی که به کدی برسند که از یک سرویس غیرمجاز استفاده می‌کند، اجرا می‌شوند و در آن نقطه متوقف می‌شوند. این فقط در صورتی صادق است که افزونه منتشر شده باشد؛ همان تریگر در یک پروژه اسکریپت برنامه‌های معمولی یا یک افزونه منتشر نشده، اگر بخشی از اسکریپت نیاز به مجوز داشته باشد، اصلاً اجرا نمی‌شود.
• تریگرهای قابل نصب تابع محدودیت‌های سهمیه تریگر Apps Script هستند.