مشغلات إضافات المحرر

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

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

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

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

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

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

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

حدث	كائن الحدث	العوامل البسيطة	العوامل المشغِّلة القابلة للتثبيت
فتح يتم فتح ملف محرّر.	كائن الحدث "مستندات onOpen" كائن الحدث "نماذج onOpen" كائن الحدث "Sheets onOpen" في "جداول بيانات Google" كائن حدث "العروض التقديمية من Google" onOpen	المستندات نماذج Google* جداول بيانات Google العروض التقديمية من Google function onOpen(e)	المستندات نماذج Google جداول بيانات Google
تثبيت تم تثبيت الإضافة.	كائن حدث onInstall	المستندات نماذج 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" عندما يفتح المستخدِم نموذجًا للردّ، بل يحدث عندما يفتح المحرِّر النموذج لتعديله.

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

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

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

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

القيود

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

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

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

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

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

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

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

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