المشغلات البسيطة

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

الخطوات الأولى

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

• يتم تشغيل onOpen(e) عندما يفتح المستخدم جدول بيانات أو مستندًا أو عرضًا تقديميًا أو نموذج لدى المستخدم إذن بتعديله.
• يتم تشغيل onInstall(e) عندما يثبّت أحد المستخدمين إضافة محرِّر من داخل "مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google" أو "نماذج Google"
• يتم تشغيل onEdit(e) عندما يغيّر المستخدم قيمة في جدول بيانات.
• يتم تشغيل onSelectionChange(e) عندما يغيّر المستخدم الاختيار في جدول بيانات.
• يتم تشغيل doGet(e) عندما يزور أحد المستخدمين تطبيق ويب. أو يرسل أحد البرامج طلب HTTP GET إلى تطبيق ويب.
• يتم تشغيل doPost(e) عندما يرسل أحد البرامج طلب HTTP POST إلى تطبيق ويب.

المعلمة e في أسماء الدوال أعلاه هي كائن الحدث الذي يتم تمريره إلى الأخرى. يحتوي الكائن على معلومات حول السياق الذي تسبّب في النار فيه، لكن استخدامها اختياري.

القيود

نظرًا لأنه يتم تنشيط المشغلات البسيطة تلقائيًا، دون طلب من المستخدم التفويض، فإنها تخضع لعدة قيود:

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

لا تنطبق هذه القيود على doGet(e) أو doPost(e).

onOpen(e)

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

/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

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

/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

يتم تشغيل مشغِّل onEdit(e) تلقائيًا عندما يغيّر المستخدم قيمة أي خلية في جدول بيانات. تستخدم معظم مشغّلات onEdit(e) المعلومات الواردة في كائن الحدث للرد بشكلٍ مناسب. فعلى سبيل المثال، تحدد الدالة onEdit(e) أدناه تعليقًا على الخلية آخر مرة تم تعديلها فيه.

/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

onSelectionChange(e)

يتم تشغيل مشغِّل onSelectionChange(e) تلقائيًا عندما يغيّر المستخدم التحديد في جدول بيانات. لتفعيل هذا المشغِّل، يجب إعادة تحميل جدول بيانات بمجرد إضافة المشغل وفي كل مرة يتم فيها فتح جدول البيانات.

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

في المثال أدناه، إذا تم تحديد خلية فارغة، تحدد الدالة onSelectionChange(e) قيمة إلى الأحمر.

/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e) وdoPost(e)

يتم تشغيل مشغِّل doGet(e) تلقائيًا عندما يزور أحد المستخدمين يرسل تطبيق الويب أو أحد البرامج طلب HTTP GET إلى تطبيق ويب. يتم تشغيل doPost(e) عندما يرسل أحد البرامج طلب HTTP POST إلى تطبيق الويب. يتم توضيح هذه المشغلات أكثر في أدلة تطبيقات الويب، خدمة HTML، وخدمة المحتوى. لاحظ أن doGet(e) و لا تخضع doPost(e) للقيود المذكورة أعلاه.

الأنواع المتاحة من المشغِّلات

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

الحدث	مشغِّلات بسيطة	المشغلات القابلة للتثبيت
فتح	function onOpen(e)
تعديل	function onEdit(e)
تغيير الاختيار	function onSelectionChange(e)
تثبيت	function onInstall(e)
تغيير
إرسال النموذج
مستندة إلى الوقت (ساعة)
جلب	function doGet(e)
نشر	function doPost(e)

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