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

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

ملاحظة: للحصول على معلومات عن طريقة استخدام عوامل التفعيل في مشاريع إضافات Google Workspace، يُرجى الاطّلاع على مقالة عوامل التفعيل لإضافات Google Workspace.

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

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

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

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

onOpen(e)

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

triggers/triggers.gs

عرض على GitHub

/**
 * 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

عرض على GitHub

/**
 * 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

عرض على GitHub

/**
 * 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());
}

ملاحظة: لا يضع المشغِّل onEdit() إلا في قائمة انتظار ما يصل إلى حدثَي تشغيل.

onSelectionChange(e)

يتم تشغيل المشغِّل onSelectionChange(e) تلقائيًا عندما يغيّر المستخدم الاختيار في جدول بيانات. لتنشيط هذا المشغل، يجب عليك تحديث جدول البيانات بمجرد إضافة المشغل وفي كل مرة يتم فيها فتح جدول البيانات.

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

في المثال أدناه، إذا تم تحديد خلية فارغة، فستضبط الدالة onSelectionChange(e) خلفية الخلية على اللون الأحمر.

triggers/triggers.gs

عرض على GitHub

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