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

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

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) عندما يرسل أحد البرامج طلب POST HTTP إلى تطبيق ويب. وتظهَر هذه المشغلات بشكل أكبر في أدلة تطبيقات الويب وخدمة HTML وخدمة المحتوى. يُرجى العلم أنّ doGet(e) وdoPost(e) لا يخضعان للقيود المذكورة أعلاه.

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

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