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

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

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

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

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

• يتم تشغيل onOpen(e) عندما يفتح المستخدم جدول بيانات أو مستندًا أو عرضًا تقديميًا أو نموذجًا لديه الإذن بتعديله.
• يتم تشغيل onInstall(e) عندما يثبّت مستخدم إضافة محرّر من داخل "مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google" أو "نماذج Google".
• يتم تشغيل onEdit(e) عندما يغيّر المستخدم قيمة في جدول بيانات.
• يتم تشغيل onSelectionChange(e) عندما يغيّر المستخدم الاختيار في جدول بيانات.
• يتم تشغيل doGet(e) عندما يزور المستخدم تطبيق ويب أو عندما يرسل برنامج طلب HTTP GET إلى تطبيق ويب.
• يتم تشغيل doPost(e) عندما يرسل برنامج طلب POST HTTP إلى تطبيق ويب.

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