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

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

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

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

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

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

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

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

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

القيود

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

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

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

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

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

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

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

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