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

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

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

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

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

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

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

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

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

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

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

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

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

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

القيود

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

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

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

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