عناصر الأحداث

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

function onEdit(e){
  // Set a comment on the edited cell to indicate when it was changed.
  var range = e.range;
  range.setNote('Last modified: ' + new Date());
}

توضّح هذه الصفحة بالتفصيل الحقول في عنصر الحدث لأنواع مختلفة من عوامل الإطلاق.

تحتوي الأحداث التي يتم إنشاؤها بواسطة المشغِّلات القابلة للتثبيت على triggerUid يحدِّد المشغِّل الذي أنشأ الحدث. ويُعدّ ذلك مفيدًا للنصوص البرمجية التي تحتوي على عدّة عوامل تشغيل قابلة للتثبيت.

أحداث "جداول بيانات Google"

تتيح عوامل التشغيل المختلفة الخاصة بخدمة Google Sheets للنصوص البرمجية الاستجابة لصنّاع المحتوى في جدول البيانات.

فتح (بسيطة وقابلة للتثبيت)
authMode	قيمة من التعداد ScriptApp.AuthMode LIMITED
source	عنصر Spreadsheet يمثّل ملف "جداول بيانات Google" المرتبط بالنص البرمجي Spreadsheet
triggerUid	رقم تعريف العامل المشغِّل الذي أدّى إلى حدوث هذا الحدث (عوامل التشغيل القابلة للتثبيت فقط) 4034124084959907503
user	عنصر User، يمثّل المستخدم النشط، في حال توفّره (حسب مجموعة معقدة من قيود الأمان). [e-mail]

تغيير (قابل للتثبيت)
authMode	قيمة من التعداد ScriptApp.AuthMode FULL
changeType	نوع التغيير (EDIT أو INSERT_ROW أو INSERT_COLUMN أو REMOVE_ROW أو REMOVE_COLUMN أو INSERT_GRID أو REMOVE_GRID أو FORMAT أو OTHER) INSERT_ROW
source	عنصر Spreadsheet يمثّل ملف "جداول بيانات Google" الذي يتم ربط النص البرمجي به. Spreadsheet
triggerUid	رقم تعريف عامل التشغيل الذي أدّى إلى حدوث هذا الحدث 4034124084959907503
user	عنصر User، يمثّل المستخدم النشط، في حال توفّره (حسب مجموعة معقدة من قيود الأمان). [e-mail]

تعديل (بسيطة وقابلة للتثبيت)
authMode	قيمة من التعداد ScriptApp.AuthMode LIMITED
oldValue	قيمة الخلية قبل التعديل، إن توفّرت لا يتوفّر إلا إذا كان النطاق المعدَّل خلية واحدة. لن يتم تحديده إذا لم تكن الخلية تحتوي على محتوى سابق. 1234
range	عنصر Range، يمثّل الخلية أو نطاق الخلايا التي تم تعديلها. Range
source	عنصر Spreadsheet يمثّل ملف "جداول بيانات Google" المرتبط بالنص البرمجي Spreadsheet
triggerUid	رقم تعريف العامل المشغِّل الذي أدّى إلى حدوث هذا الحدث (عوامل التشغيل القابلة للتثبيت فقط) 4034124084959907503
user	عنصر User، يمثّل المستخدم النشط، في حال توفّره (حسب مجموعة معقدة من قيود الأمان). [e-mail]
value	قيمة الخلية الجديدة بعد التعديل لا يتوفّر إلا إذا كان النطاق المعدَّل هو خلية واحدة. 10

إرسال النموذج (قابل للتثبيت)
ملاحظة: تأكَّد من استخدام عبارة تشغيل إرسال النموذج هذه مع SpreadsheetTriggerBuilder.
authMode	قيمة من التعداد ScriptApp.AuthMode FULL
namedValues	عنصر يحتوي على أسماء الأسئلة وقيمها من عملية إرسال النموذج { 'First Name': ['Jane'], 'Timestamp': ['6/7/2015 20:54:13'], 'Last Name': ['Doe'] }
range	عنصر Range، يمثّل الخلية أو نطاق الخلايا التي تم تعديلها. Range
triggerUid	رقم تعريف عامل التشغيل الذي أدّى إلى حدوث هذا الحدث 4034124084959907503
values	صفيف يحتوي على قيم بالترتيب نفسه الذي تظهر به في جدول البيانات ['2015/05/04 15:00', '[e-mail]', 'Bob', '27', 'Bill', '28', 'Susan', '25']

أحداث "مستندات Google"

تسمح عوامل التفعيل لخدمة "مستندات Google" بالاستجابة عندما يفتح أحد المستخدمين مستندًا.

فتح (بسيطة وقابلة للتثبيت)
authMode	قيمة من التعداد ScriptApp.AuthMode LIMITED
source	عنصر Document، يمثّل ملف "مستندات Google" المرتبط بالنص البرمجي. Document
triggerUid	رقم تعريف العامل المشغِّل الذي أدّى إلى حدوث هذا الحدث (عوامل التشغيل القابلة للتثبيت فقط) 4034124084959907503
user	عنصر User، يمثّل المستخدم النشط، في حال توفّره (حسب مجموعة معقدة من قيود الأمان). [e-mail]

أحداث "العروض التقديمية من Google"

تسمح عوامل التفعيل لخدمة "العروض التقديمية من Google" بالاستجابة عندما يفتح أحد المستخدمين عرضًا تقديميًا.

فتح (بسيطة)
authMode	قيمة من التعداد ScriptApp.AuthMode LIMITED
source	عنصر Presentation، يمثّل ملف "العروض التقديمية من Google" المرتبط بالنص البرمجي. Presentation
user	عنصر User، يمثّل المستخدم النشط، في حال توفّره (حسب مجموعة معقدة من قيود الأمان). [e-mail]

أحداث "نماذج Google"

تسمح عوامل التشغيل الخاصة بخدمة "نماذج Google" للنصوص البرمجية بالردّ عندما يعدّل مستخدم نموذجًا أو يرسل ردًا.

فتح * (بسيطة وقابلة للتثبيت)
authMode	قيمة من التعداد ScriptApp.AuthMode LIMITED
source	عنصر Form، يمثّل ملف "نماذج Google" المرتبط بالنص البرمجي. Form
triggerUid	رقم تعريف العامل المشغِّل الذي أدّى إلى حدوث هذا الحدث (عوامل التشغيل القابلة للتثبيت فقط) 4034124084959907503
user	عنصر User، يمثّل المستخدم النشط، في حال توفّره (حسب مجموعة معقدة من قيود الأمان). [e-mail]

* لا يحدث هذا الحدث عندما يفتح مستخدم نموذجًا للردّ، بل عند فتح محرِّر النموذج لتعديله.

إرسال النموذج (قابل للتثبيت)
تنبيه: تأكَّد من استخدام عبارة تشغيل إرسال النموذج هذه مع FormTriggerBuilder.
authMode	قيمة من التعداد ScriptApp.AuthMode FULL
response	عنصر FormResponse، يمثّل ردّ المستخدم على النموذج ككل FormResponse
source	عنصر Form، يمثّل ملف "نماذج Google" المرتبط بالنص البرمجي. Form
triggerUid	رقم تعريف عامل التشغيل الذي أدّى إلى حدوث هذا الحدث 4034124084959907503

أحداث "تقويم Google"

يتم تنشيط "تقويم Google" عند تعديل أحداث تقويم المستخدم (إنشاء أو تعديل أو حذف).

ولا تُعلمك هذه المشغّلات بالحدث الذي تغيّر أو كيف تغيّر. بدلاً من ذلك، تشير إلى أنّ الرمز البرمجي يحتاج إلى إجراء عملية مزامنة تدريجية لالتقاط التغييرات الأخيرة في التقويم. للحصول على وصف كامل لهذه العملية، يُرجى الاطّلاع على دليل مزامنة الموارد لواجهة برمجة التطبيقات Calendar API.

للمزامنة مع "تقويم Google" في Apps Script، اتّبِع الخطوات التالية:

1. فعِّل الخدمة المتقدّمة في "تقويم Google" ل مشروع النص البرمجي. إنّ خدمة التقويم المضمّنة ليست كافية للقيام بهذه العملية.
2. حدِّد التقاويم التي يجب مزامنتها. لكل تقويم من هذه التقاويم، نفِّذ عملية مزامنة أولية باستخدام الأسلوب Events.list() لخدمة "تقويم Google" المتقدّمة.
3. تؤدي نتيجة المزامنة الأولية إلى عرض nextSyncToken لذلك التقويم. تخزين هذا الرمز المميّز لاستخدامه لاحقًا
4. عند بدء تشغيل عامل تشغيل EventUpdated في Apps Script للإشارة إلى تغيُّر حدث في تقويم، يمكنك إجراء مزامنة تدريجية للتقويم المتأثر باستخدام nextSyncToken المخزَّن. هذا هو طلب Events.list() آخر، ولكنّ تقديم nextSyncToken يحدّ من الاستجابة لتشمل الأحداث التي تم تغييرها فقط منذ آخر عملية مزامنة.
5. راجِع استجابة المزامنة لمعرفة الأحداث التي تم تعديلها وأعدّ رمزك للردّ بشكل مناسب. على سبيل المثال، يمكنك تسجيل التغيير أو تعديل جدول بيانات أو إرسال إشعارات عبر البريد الإلكتروني أو اتّخاذ إجراءات أخرى.
6. عدِّل nextSyncToken الذي حفظته لهذا التقويم باستخدام القيمة التي تم عرضها بواسطة طلب المزامنة المتزايدة. يؤدي ذلك إلى فرض إجراء عملية المزامنة التالية لمحاولة عرض أحدث التغييرات فقط.

تحذير: في بعض الأحيان، يبطل الخادم رمز مفتاح المزامنة، ما يؤدي إلى خطأ 410. عند حدوث ذلك، من المفترض أن يُجري الرمز البرمجي عملية مزامنة كاملة ويحلّ محل جميع البيانات المتزامنة والرموز المخزّنة التي لديك لهذا التقويم.

EventUpdated (قابل للتثبيت)
authMode	قيمة من التعداد ScriptApp.AuthMode FULL
calendarId	رقم تعريف السلسلة للتقويم الذي حدث فيه تعديل الحدث. [e-mail]
triggerUid	رقم تعريف عامل التشغيل الذي أدّى إلى حدوث هذا الحدث 4034124084959907503

أحداث إضافات Google Workspace

يتم تنفيذ العامل المشغِّل onInstall() تلقائيًا عندما يتثبّت أحد المستخدِمين إضافة.

تثبيت (بسيطة)
authMode	قيمة من التعداد ScriptApp.AuthMode FULL

أحداث تطبيق Google Chat

للتعرّف على عناصر الأحداث في Google Chat، اطّلِع على مقالة تلقّي التفاعلات والردّ عليها باستخدام تطبيق Google Chat.

الأحداث المستندة إلى الوقت

العوامل المشغِّلة المستندة إلى الوقت (المعروفة أيضًا باسم عوامل التشغيل بالاستناد إلى الساعة) تسمح بتنفيذ النصوص البرمجية في وقت معيّن أو في فاصل زمني متكرّر.

مستندة إلى الوقت (قابلة للتثبيت)
authMode	قيمة من التعداد ScriptApp.AuthMode FULL
day-of-month	بين 1 و31 بما أنّ اسم هذا الموقع يحتوي على شرطات، يجب الوصول إليه من خلال e['day-of-month'] بدلاً من علامة النقطة. 31
day-of-week	بين 1 (الاثنين) و7 (الأحد). بما أنّ اسم هذا الموقع يحتوي على شرطات، يجب الوصول إليه من خلال e['day-of-week'] بدلاً من علامة النقطة. 7
hour	بين 0 و23 23
minute	بين 0 و59 59
month	بين 1 و12 12
second	بين 0 و59 59
timezone	المنطقة الزمنية UTC
triggerUid	رقم تعريف عامل التشغيل الذي أدّى إلى حدوث هذا الحدث 4034124084959907503
week-of-year	بين 1 و52 بما أنّ اسم هذا الموقع يحتوي على شرطات، يجب الوصول إليه من خلال e['week-of-year'] بدلاً من علامة النقطة. 52
year	السنة. 2015