تسمح عوامل التشغيل لتطبيق Apps Script بتنفيذ دالة تلقائيًا عند وقوع حدث معيّن، مثل فتح مستند. عوامل التفعيل البسيطة هي مجموعة
من الدوال المحجوزة المضمّنة في Apps Script، مثل الدالة onOpen(e)
،
التي يتم تنفيذها عندما يفتح مستخدم ملفًا في "مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google" أو "نماذج Google".
توفّر العوامل المشغِّلة القابلة للتثبيت مزيدًا من
الإمكانات مقارنةً بالعوامل المشغِّلة البسيطة، ولكن يجب تفعيلها قبل استخدامها. بالنسبة إلى كلا
نوعَي المشغِّلات، تُرسِل Apps Script الدالة التي تم بدء تشغيلها مع كائن حدث يحتوي على معلومات
عن السياق الذي حدث فيه الحدث.
الخطوات الأولى
لاستخدام عامل تشغيل بسيط، ما عليك سوى إنشاء دالة تستخدِم أحد أسماء الدوال التالية المُخصّصة:
- يتم تشغيل
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)
البسيطة في وضع عدم التفويض الذي يقدّم بعض التعقيدات الإضافية. لمزيد من المعلومات، يمكنك الاطّلاع على دليل دورة حياة التفويض الإضافية. - تخضع المشغّلات البسيطة لالحصص المفروضة على مشغّلات Apps Script.
لا تنطبق هذه القيود على 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)
عندما يرسل برنامج طلب HTTP POST
إلى
تطبيق ويب. يتم توضيح المزيد من المعلومات عن عوامل التشغيل هذه في أدلة
تطبيقات الويب وخدمة HTML
وخدمة المحتوى. يُرجى العِلم أنّ doGet(e)
و
doPost(e)
لا يخضعان للقيود المذكورة أعلاه.
الأنواع المتاحة من المشغّلات
إذا كانت القيود المفروضة على المشغّلات البسيطة تمنع التطبيق من تلبية احتياجاتك، قد يكون مشغّل قابل للتثبيت هو الحلّ المناسب. يلخّص الجدول التالي أنواع عوامل التفعيل المتاحة لكل نوع من أنواع الأحداث. على سبيل المثال، تتيح "جداول بيانات Google" و"العروض التقديمية من Google" و"نماذج Google" و "مستندات Google" جميعها استخدام عوامل تشغيل مفتوحة بسيطة، ولكن "جداول بيانات Google" و"مستندات Google" و"نماذج Google" فقط هي التي تتيح استخدام عوامل تشغيل مفتوحة قابلة للتثبيت.
الحدث | المشغِّلات البسيطة | المشغِّلات القابلة للتثبيت |
---|---|---|
فتح |
|
|
تعديل |
|
|
تغيير الاختيار |
|
|
تثبيت |
|
|
تغيير |
|
|
إرسال النموذج |
|
|
مستندة إلى الوقت (الساعة) |
|
|
جلب |
|
|
نشر |
|
* لا يحدث حدث الفتح في "نماذج Google" عندما يفتح مستخدم ملفًا شخصيًا لتسجيل ردّ، بل عندما يفتح محرِّر النموذج لتعديله.