محرک‌های افزونه‌های ویرایشگر

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

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

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

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

انواع ماشه افزودنی ویرایشگر

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

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

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

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

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

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

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

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

محدودیت ها

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

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

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

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

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

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

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

• راه‌اندازهای قابل نصب Form-submit هنگام ارسال پاسخ Google Form اجرا می‌شوند.

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

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

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

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

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

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

/**
 * 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.
  }
}

<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>

محدودیت ها

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

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

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