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

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

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

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