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

تسمح عوامل التشغيل لتطبيق Apps Script بتنفيذ دالة تلقائيًا عند وقوع حدث معيّن، مثل فتح مستند. المشغلات البسيطة هي مجموعة من الدوال المحجوزة المضمّنة في "برمجة تطبيقات Google"، مثل الدالة 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) تلقائيًا ما لم يتم إعادة فتح الملف.

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" عندما يفتح مستخدم ملفًا شخصيًا لتسجيل ردّ، بل عندما يفتح محرِّر النموذج لتعديله.