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

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

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

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

  • يتم تشغيل 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) البسيطة في وضع عدم التفويض الذي يقدّم بعض التعقيدات الإضافية. لمزيد من المعلومات، يمكنك الاطّلاع على دليل دورة حياة التفويض الإضافية.
  • تخضع المشغّلات البسيطة لالحصص المفروضة على مشغّلات Apps Script.

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

onOpen(e)

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

triggers/triggers.gs
/**
 * 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) قوائم مخصّصة. بعد كل شيء، عند تثبيت إحدى الإضافات، يكون الملف مفتوحًا، وبالتالي لا يتم تشغيل onOpen(e) تلقائيًا ما لم يتم إعادة فتح الملف.

triggers/triggers.gs
/**
 * 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) أدناه تعليقًا على الخلية الذي يسجِّل آخر مرة تم فيها تعديلها.

triggers/triggers.gs
/**
 * 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) خلفية الخلية على اللون الأحمر.

triggers/triggers.gs
/**
 * 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" و"نماذج Google" فقط هي التي تتيح استخدام عوامل تشغيل مفتوحة قابلة للتثبيت.

الحدث المشغِّلات البسيطة المشغِّلات القابلة للتثبيت
فتح
جداول بيانات Google
العروض التقديمية من Google
نماذج Google*
مستندات Google

function onOpen(e)
جداول بيانات Google
نماذج Google*
مستندات Google
تعديل
جداول بيانات Google

function onEdit(e)
جداول بيانات Google
تغيير الاختيار
جداول بيانات Google

function onSelectionChange(e)
تثبيت
جداول بيانات Google
العروض التقديمية من Google
نماذج Google
مستندات Google

function onInstall(e)
تغيير
جداول بيانات Google
إرسال النموذج
جداول بيانات Google
نماذج Google
مستندة إلى الوقت (الساعة)
جداول بيانات Google
العروض التقديمية من Google
نماذج Google
مستندات Google
التطبيقات المستقلة
جلب
مستقلة

function doGet(e)
نشر
مستقلة

function doPost(e)

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