العوامل المُشغِّلة البسيطة

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

function doGet(e)

مشاركة
مواقع Google
مستقلة

function doPost(e)

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