تسمح المشغلات لـ "برمجة التطبيقات" بتشغيل وظيفة تلقائيًا عند وقوع حدث معين، مثل فتح مستند. المشغلات البسيطة هي مجموعة من الدوال المحجوزة المضمّنة في "برمجة تطبيقات Google"، مثل الدالة onOpen(e)
، التي يتم تنفيذها عندما يفتح المستخدم ملفًا في "مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google" أو "نماذج Google".
توفر المشغلات القابلة للتثبيت إمكانات أكثر من المشغلات البسيطة ولكن يجب تنشيطها قبل الاستخدام. بالنسبة إلى كلا نوعَي العوامل المُشغِّلة، تمرِّر "برمجة تطبيقات Google" الدالة المُشغَّلة كائن حدث يحتوي على معلومات حول السياق الذي وقع فيه الحدث.
الخطوات الأولى
لاستخدام مشغل بسيط، ما عليك سوى إنشاء دالة تستخدم أحد أسماء الدوال المحجوزة التالية:
- يتم تشغيل
onOpen(e)
عندما يفتح المستخدم جدول بيانات أو مستندًا أو عرضًا تقديميًا أو نموذجًا لديه إذن بتعديله. - يتم تشغيل
onInstall(e)
عندما يثبّت أحد المستخدمين إضافة محرِّر من داخل "مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google" أو "نماذج Google". - يتم تشغيل
onEdit(e)
عندما يغيّر المستخدم قيمة في جدول بيانات. - يتم تشغيل
onSelectionChange(e)
عندما يغيّر المستخدم الاختيار في جدول بيانات. - تعمل السمة
doGet(e)
عندما يزور أحد المستخدمين تطبيق ويب، أو يرسل أحد البرامج طلب HTTPGET
إلى تطبيق ويب. - يتم تشغيل
doPost(e)
عندما يرسل أحد البرامج طلب HTTPPOST
إلى تطبيق ويب.
المعلمة 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".
onInstall(e)
يتم تشغيل المشغِّل onInstall(e)
تلقائيًا عندما يثبّت أحد المستخدمين إضافة محرِّر من داخل "مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google" أو "نماذج Google". لن يتم تشغيل المشغّل عندما يثبِّت
مستخدم الإضافة من موقع
Google Workspace Marketplace الإلكتروني. يُرجى العلم أنّ هناك قيودًا معيّنة على الإجراءات التي يمكن لـ "onInstall(e)
" تنفيذها. تعرَّف على مزيد من المعلومات حول التفويض.
الاستخدام الأكثر شيوعًا لـ onInstall(e)
هو ببساطة استدعاء onOpen(e)
لإضافة
قوائم مخصصة. بعد تثبيت إضافة، يكون الملف مفتوحًا، وبالتالي لن يعمل onOpen(e)
من تلقاء نفسه ما لم تتم إعادة فتح الملف.
onEdit(e)
يتم تشغيل المشغِّل onEdit(e)
تلقائيًا عندما يغيّر المستخدم قيمة أي خلية في جدول بيانات. تستخدم معظم مشغِّلات onEdit(e)
المعلومات الواردة في
كائن الحدث للرد بشكلٍ مناسب.
على سبيل المثال، تحدد الدالة onEdit(e)
أدناه تعليقًا على الخلية
يسجّل آخر مرة تم تعديلها فيها.
onSelectionChange(e)
يتم تشغيل المشغِّل onSelectionChange(e)
تلقائيًا عندما يغيّر المستخدم الاختيار في جدول بيانات. لتنشيط هذا المشغل، يجب عليك تحديث جدول البيانات
بمجرد إضافة المشغل وفي كل مرة يتم فيها فتح جدول البيانات.
إذا كان التحديد ينتقل بين عدة خلايا في وقت قصير، يمكن تخطي بعض أحداث تغيير التحديد لتقليل وقت الاستجابة. على سبيل المثال، إذا تم إجراء العديد من تغييرات الاختيار خلال ثانيتين من بعضها، سيؤدي إجراء التغييرات الأولى والأخيرة فقط إلى تفعيل المشغّل onSelectionChange(e)
.
في المثال أدناه، إذا تم تحديد خلية فارغة، فستضبط الدالة onSelectionChange(e)
خلفية الخلية على اللون الأحمر.
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" عندما يفتح المستخدم نموذجًا للرد، ولكن عند فتح أحد المحرِّرين للنموذج لتعديله.