عوامل تشغيل إضافات المحرِّر

تؤدي علامات تشغيل "برمجة التطبيقات" إلى تنفيذ دالة نص برمجي محدّدة (دالة علامة التشغيل) كلّما وقع حدث محدّد. لا يمكن أن تؤدي إلا أحداث معيّنة إلى تشغيل علامات التشغيل، ويدعم كل تطبيق من تطبيقات Google Workspace مجموعة مختلفة من الأحداث.

عند تشغيل علامة تشغيل، يتم إنشاء كائن حدث. يحتوي هذا البنية بتنسيق JSON على تفاصيل حول الحدث الذي وقع. يتم تنظيم المعلومات في بنية كائن الحدث بشكل مختلف استنادًا إلى نوع علامة التشغيل.

بعد إنشاء كائن الحدث، تمرّره "برمجة التطبيقات" كمعلَمة إلى دالة علامة التشغيل. دالة المشغِّل هي دالّة رد الاتصال يجب تنفيذها بنفسك لاتخاذ أي إجراءات مناسبة للردّ على الحدث. على سبيل المثال، في إضافة المحرّر، يتم استخدام علامة تشغيل لإنشاء عناصر قائمة الإضافة عند فتح مستند. في هذه الحالة، يمكنك تنفيذ دالة علامة التشغيل onOpen(e) لإنشاء عناصر القائمة التي تحتاجها الإضافة، ربما باستخدام البيانات في كائن الحدث.

تقدّم هذه الصفحة إرشادات حول استخدام علامات التشغيل في مشاريع إضافات المحرّر.

أنواع علامات تشغيل إضافات المحرّر

يمكنك استخدام معظم أنواع علامات التشغيل العامة المتاحة لمشاريع "برمجة تطبيقات Google" في إضافات المحرّر، بما في ذلك علامات التشغيل البسيطة ومعظم علامات التشغيل القابلة للتثبيت. تعتمد المجموعة الدقيقة لأنواع علامات التشغيل المتاحة على التطبيق الذي يتم توسيعه.

على عكس إضافات أدوات التحرير، لا يمكن لإضافات Google Workspace استخدام علامات التشغيل البسيطة أو القابلة للتثبيت العامة في "برمجة التطبيقات". بدلاً من ذلك، تستخدم علامات تشغيل مصمّمة خصيصًا لإضافات Google Workspace. لمزيد من المعلومات، يُرجى الاطّلاع على علامات تشغيل إضافات Google Workspace.

يوضّح الجدول التالي أنواع علامات التشغيل البسيطة والقابلة للتثبيت التي يمكن أن تستخدمها إضافات المحرّر، ويقدّم روابط إلى كائنات الأحداث المقابلة:

الحدث	كائن الحدث	علامات التشغيل البسيطة	علامات التشغيل القابلة للتثبيت
فتح يتم فتح ملف في المحرّر.	كائن حدث onOpen في "مستندات Google" كائن حدث onOpen في "نماذج Google" كائن حدث onOpen في "جداول بيانات Google" كائن حدث onOpen في "العروض التقديمية من Google"	مستندات Google نماذج Google* جداول بيانات Google العروض التقديمية من Google function onOpen(e)	مستندات Google نماذج Google جداول بيانات Google
تثبيت يتم تثبيت الإضافة.	كائن حدث onInstall	مستندات Google نماذج Google جداول بيانات Google العروض التقديمية من Google function onInstall(e)
تعديل يتم تغيير محتوى خلية جدول البيانات.	كائن حدث onEdit في "جداول بيانات Google"	جداول بيانات Google function onEdit(e)	جداول بيانات Google
تغيير يتم تعديل المحتوى في ورقة أو تنسيقه.	كائن حدث onChange في "جداول بيانات Google"		جداول بيانات Google
إرسال النموذج يتم إرسال "نموذج Google".	كائن حدث form-submit في "نماذج Google" كائن حدث form-submit في "جداول بيانات Google"		نماذج Google جداول بيانات Google
مستند إلى الوقت (الساعة) يتم تشغيل علامة التشغيل في وقت أو فاصل زمني محدّدَين.	كائن الحدث المستند إلى الوقت	مستندات Google نماذج Google جداول بيانات Google العروض التقديمية من Google

* لا يظهر حدث الفتح في "نماذج Google" عندما يفتح المستخدم نموذجًا للردّ عليه، ولكن عندما يفتح المحرّر النموذج لتعديله.

علامات التشغيل البسيطة في الإضافات

تستخدم علامات التشغيل البسيطة مجموعة من أسماء الدوال المحجوزة، ولا يمكنها استخدام الخدمات التي تتطلب تفويضًا، ويتم تفعيلها تلقائيًا لاستخدامها. في بعض الحالات، يمكن أن تتعامل علامة تشغيل بسيطة مع حدث علامة تشغيل قابلة للتثبيت بدلاً من ذلك.

يمكنك إضافة علامة تشغيل بسيطة إلى إضافة من خلال تنفيذ دالة بأحد الأسماء المحجوزة التالية:

• يتم تنفيذ onOpen عندما يفتح المستخدم مستندًا أو جدول بيانات أو عرضًا تقديميًا. يمكن أيضًا تنفيذ onOpen عند فتح نموذج في المحرّر (ولكن ليس عند الردّ على النموذج). لا يتم تنفيذها إلا إذا كان لدى المستخدم إذن تعديل الملف المعني، وغالبًا ما تُستخدم لإنشاء عناصر القائمة.
• يتم تنفيذ onInstall عندما يثبِّت المستخدم إضافة. عادةً ما تُستخدم onInstall فقط لاستدعاء onOpen، ما يضمن ظهور قوائم الإضافة فورًا بعد التثبيت بدون أن يضطر المستخدم إلى إعادة تحميل الصفحة.
• يتم تنفيذ onEdit عندما يغيّر المستخدم قيمة خلية في جدول بيانات. لا يتم تشغيل علامة التشغيل هذه استجابةً لنقل الخلايا أو تنسيقها أو إجراء تغييرات أخرى لا تغيّر قيم الخلايا.

القيود

تخضع علامات التشغيل البسيطة في الإضافات للقيود نفسها التي تحكم علامات التشغيل البسيطة في أنواع مشاريع "برمجة التطبيقات" الأخرى. يُرجى الانتباه بشكل خاص إلى هذه القيود عند تصميم الإضافات:

• لا يتم تشغيل علامات التشغيل البسيطة إذا تم فتح ملف في وضع القراءة فقط (العرض أو التعليق). يمنع هذا السلوك ملء قوائم الإضافة.
• في ظروف معيّنة، تشغّل إضافات المحرّر علامات التشغيل البسيطة onOpen وonEdit في وضع بدون تفويض. يؤدي هذا الوضع إلى حدوث تعقيدات كما هو موضّح في الـ نموذج تفويض الإضافة.
• لا يمكن لعلامات التشغيل البسيطة استخدام الخدمات أو اتخاذ إجراءات أخرى تتطلب تفويضًا، باستثناء ما هو موضّح في نموذج تفويض الإضافة.
• لا يمكن أن تستمر علامات التشغيل البسيطة لأكثر من 30 ثانية. قلِّل مقدار المعالجة التي يتم إجراؤها في دالة علامة التشغيل البسيطة.
• تخضع علامات التشغيل البسيطة لحدود الحصص المفروضة على علامات تشغيل "برمجة التطبيقات" .

علامات التشغيل القابلة للتثبيت في الإضافات

يمكن للإضافات إنشاء علامات تشغيل قابلة للتثبيت وتعديلها آليًا باستخدام خدمة Script في "برمجة التطبيقات". لا يمكن إنشاء علامات تشغيل الإضافات القابلة للتثبيت يدويًا. على عكس علامات التشغيل البسيطة، يمكن لعلامات التشغيل القابلة للتثبيت استخدام الخدمات التي تتطلب تفويضًا.

لا تُرسِل علامات التشغيل القابلة للتثبيت في الإضافات رسائل إلكترونية تتضمّن أخطاءً إلى المستخدم عندما تواجه أخطاءً، لأنّه في معظم الحالات لا يمكن للمستخدم معالجة المشكلة. لهذا السبب، يجب تصميم الإضافة للتعامل مع الأخطاء نيابةً عن المستخدم كلما أمكن ذلك.

يمكن للإضافات استخدام علامات التشغيل القابلة للتثبيت التالية:

• يتم تنفيذ علامات التشغيل القابلة للتثبيت فتح عندما يفتح المستخدم مستندًا أو جدول بيانات أو عندما يتم فتح نموذج في المحرّر (ولكن ليس عند الردّ على النموذج).
• يتم تنفيذ علامات التشغيل القابلة للتثبيت تعديل عندما يغيّر المستخدم قيمة خلية في جدول بيانات. لا يتم تشغيل علامة التشغيل هذه استجابةً للتنسيق أو إجراء تغييرات أخرى لا تغيّر قيم الخلايا.
• يتم تنفيذ علامات التشغيل القابلة للتثبيت تغيير عندما يُجري المستخدم أي تغيير في جدول بيانات، بما في ذلك تعديلات التنسيق والتعديلات على جدول البيانات نفسه (مثل إضافة صف).

• يتم تنفيذ علامات التشغيل القابلة للتثبيت إرسال النموذج عندما يتم إرسال ردّ على "نموذج Google".

  هناك إصداران من علامات تشغيل إرسال النموذج: أحدهما في "جداول بيانات Google" (حيث يتم جمع الردود على النموذج) والآخر في "نماذج Google". يكون كائن الحدث الذي يتم تمريره إلى دالة علامة تشغيل إرسال النموذج في "جداول بيانات Google" أبسط ويعرض قيم الردود في مصفوفات بسيطة. يقدّم كائن الحدث الذي يتم تمريره إلى دالة علامة تشغيل إرسال النموذج في "نماذج Google" مزيدًا من المعلومات، الواردة في FormResponse كائن.

• يتم تشغيل علامات التشغيل المستندة إلى الوقت (تُعرف أيضًا بعلامات تشغيل الساعة) في وقت محدّد أو بشكل متكرّر على فاصل زمني منتظم.

تفويض علامات التشغيل القابلة للتثبيت

عادةً، إذا عدّل أحد المطوّرين إضافة لاستخدام خدمات جديدة تتطلب تفويضًا إضافيًا، يُطلب من المستخدمين إعادة تفويض الإضافة في المرة التالية التي يستخدمونها فيها.

ومع ذلك، تواجه الإضافات التي تستخدم علامات التشغيل تحديات تفويض خاصة. لنفترض أنّ هناك إضافة تستخدم علامة تشغيل لتتبُّع عمليات إرسال النماذج: قد يفوّض منشئ النموذج الإضافة في المرة الأولى التي يستخدمها فيها، ثم يتركها تعمل لأشهر أو سنوات بدون إعادة فتح النموذج مطلقًا. إذا عدّل مطوّر الإضافة الإضافة لاستخدام خدمات جديدة تتطلب تفويضًا إضافيًا، لن يرى منشئ النموذج أبدًا مربّع حوار إعادة التفويض لأنّه لم يعِد فتح النموذج مطلقًا، وستتوقف الإضافة عن العمل.

على عكس علامات التشغيل في مشاريع "برمجة التطبيقات" العادية، تستمر علامات التشغيل في الإضافات في التشغيل حتى إذا كانت بحاجة إلى إعادة التفويض. ومع ذلك، لا يزال النص البرمجي يتعذّر تنفيذه إذا وصل إلى سطر من التعليمات البرمجية يتطلب تفويضًا غير متوفّر لديه. لتجنُّب ذلك، استخدِم ScriptApp.getAuthorizationInfo للتحكّم في الوصول إلى أجزاء من التعليمات البرمجية التي تم تغييرها بين إصدارات الإضافة.

توضّح الأمثلة التالية البنية المقترَحة التي يجب استخدامها في دوال علامات التشغيل لتجنُّب أخطاء التفويض. تستجيب دالة علامة التشغيل النموذجية لحدث إرسال نموذج ضِمن إضافة في "جداول بيانات Google"، وفي حال الحاجة إلى إعادة التفويض، تُرسِل رسالة إلكترونية تنبيهية إلى مستخدم الإضافة باستخدام HTML مستند إلى نموذج.

Code.gs

triggers/form/Code.gs

عرض على GitHub

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

authorizationemail.html

triggers/form/AuthorizationEmail.html

عرض على GitHub

<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" أ إنشاء علامة تشغيل لتتبُّع وقت فتح "مستند Google" ب.
• لا يمكن أن يتم تشغيل علامات التشغيل المستندة إلى الوقت أكثر من مرة واحدة في الساعة.
• لا تُرسِل الإضافات تلقائيًا رسالة إلكترونية إلى المستخدم عندما يعرض رمز يتم تشغيله بواسطة علامة تشغيل قابلة للتثبيت استثناءً. على المطوّر التحقّق من حالات الفشل والتعامل معها بشكل مناسب.
• تتوقف علامات تشغيل الإضافة عن التشغيل في أي من الحالات التالية:
  • إذا أزال المستخدم تثبيت الإضافة،
  • إذا تم إيقاف الإضافة في مستند (إذا تم إعادة تفعيلها، تصبح علامة التشغيل نشطة مرة أخرى)، أو
  • إذا ألغى المطوّر نشر الإضافة أو أرسل إصدارًا معطّلاً إلى متجر الإضافات.
• يتم تنفيذ دوال علامات تشغيل الإضافة إلى أن تصل إلى رمز يستخدم خدمة غير مسموح بها، وعند هذه النقطة تتوقف. لا ينطبق ذلك إلا إذا تم نشر الإضافة، ولا يتم تنفيذ علامة التشغيل نفسها في مشروع "برمجة التطبيقات" العادي أو الإضافة غير المنشورة على الإطلاق إذا كان أي جزء من النص البرمجي يحتاج إلى تفويض.
• تخضع علامات التشغيل القابلة للتثبيت لحدود الحصص المفروضة على علامات تشغيل "برمجة التطبيقات" .