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