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

راه‌اندازهای 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 هستند.

راه‌اندازهای 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 هستند.

راه‌اندازهای 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 هستند.

راه‌اندازهای 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) هنگامی که کاربر مقدار سلول را در صفحه گسترده تغییر می دهد ، اجرا می شود. این ماشه در پاسخ به حرکات سلول ، قالب بندی یا سایر تغییراتی که مقادیر سلول را تغییر نمی دهد ، آتش نمی گیرد.

محدودیت ها

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

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

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

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

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

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

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

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

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

مجوز محرک های قابل نصب

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

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

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

در زیر نمونه ای از ساختار توصیه شده برای استفاده در توابع ماشه برای جلوگیری از مشکلات مجوز. عملکرد Trigger مثال به یک رویداد فرمیت فرم در یک افزودنی 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>

محدودیت ها

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

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

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