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

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

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

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

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

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

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

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

القيود

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

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

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

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

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

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

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

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

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

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

منح الإذن للعوامل المشغِّلة القابلة للتثبيت

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

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

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