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

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

/**
 * 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) بمفرده، ما لم تتم إعادة فتح الملف.

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

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

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

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

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

الحدث	عوامل التشغيل البسيطة	العوامل المشغِّلة القابلة للتثبيت
فتح	function onOpen(e)
تعديل	function onEdit(e)
تغيير الاختيار	function onSelectionChange(e)
تثبيت	function onInstall(e)
تغيير
تقديم النموذج
مستند إلى الوقت (الساعة)
جلب	function doGet(e)
في المنتدى	function doPost(e)

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