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

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

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

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

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

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

المَعلمة 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

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