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

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

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

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

تقدّم هذه الصفحة إرشادات حول استخدام عوامل التفعيل في مشاريع تطبيقات Chrome الملحقة بالمحرِّر.

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

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

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

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

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

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

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

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

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

القيود

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

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

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

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

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

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

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

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

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

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

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

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

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

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

بالإضافة إلى هذه القيود، تنطبق عدة قيود على عوامل التفعيل التي يمكن تثبيتها في الإضافات على وجه التحديد:

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