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

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

البدء

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

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

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

القيود

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

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

لا تسري هذه القيود على doGet(e) أو doPost(e).

onOpen(e)

يتم تشغيل المشغِّل onOpen(e) تلقائيًا عندما يفتح المستخدم جدول بيانات أو مستندًا أو عرضًا تقديميًا أو نموذجًا يكون لديه إذن بتعديله. (لا يتم تشغيل المشغل عند الاستجابة لنموذج، فقط عند فتح النموذج لتحريره). يتم استخدام onOpen(e) بشكل شائع لإضافة عناصر قائمة مخصصة إلى "جداول بيانات Google" أو "العروض التقديمية من 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) تلقائيًا عندما يزور المستخدم تطبيق ويب أو يرسل برنامج طلب GET HTTP إلى تطبيق ويب. يتم تشغيل doPost(e) عندما يرسل برنامج طلب POST HTTP إلى تطبيق ويب. يتم توضيح هذه المشغلات بشكل أكبر في أدلة تطبيقات الويب وخدمة HTML وخدمة المحتوى. يُرجى العلم أنّ doGet(e) وdoPost(e) لا يخضعان للقيود المذكورة أعلاه.

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

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

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

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