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

تتيح العوامل المشغِّلة البسيطة والعوامل المشغِّلة القابلة للتثبيت لخدمة برمجة تطبيقات Google تشغيل دالة تلقائيًا عند وقوع حدث معيّن. عندما يتم تنشيط مشغّل، تمرّر برمجة تطبيقات إلى الدالة عنصر حدث كوسيطة، ويكون عادةً 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" للبرامج النصية الاستجابة لإجراءات المستخدم في جدول بيانات.

فتح (بسيط وقابل للتثبيت)
`authMode`	قيمة من التعداد `ScriptApp.AuthMode` LIMITED
`source`	كائن `Spreadsheet` يمثّل ملف "جداول بيانات Google" الذي يرتبط به النص البرمجي. Spreadsheet
`triggerUid`	معرّف عامل التشغيل الذي أدّى إلى إنشاء هذا الحدث (عوامل التشغيل القابلة للتثبيت فقط) 4034124084959907503
`user`	كائن `User`، يمثّل المستخدم النشط، إذا كان متاحًا (حسب مجموعة معقّدة من قيود الأمان). amin@example.com

تغيير (قابلة للتثبيت)
`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`، يمثّل المستخدم النشط، إذا كان متاحًا (حسب مجموعة معقّدة من قيود الأمان). amin@example.com

تعديل (بسيط وقابل للتثبيت)
`authMode`	قيمة من التعداد `ScriptApp.AuthMode` LIMITED
`oldValue`	قيمة الخلية قبل التعديل، إن وُجدت لا يتوفّر هذا الخيار إلا إذا كان النطاق المعدَّل خلية واحدة. تكون القيمة غير محدّدة إذا لم تتضمّن الخلية أي محتوى سابق. 1234
`range`	كائن `Range` يمثّل الخلية أو نطاق الخلايا التي تم تعديلها. Range
`source`	كائن `Spreadsheet` يمثّل ملف "جداول بيانات Google" الذي يرتبط به النص البرمجي. Spreadsheet
`triggerUid`	معرّف عامل التشغيل الذي أدّى إلى إنشاء هذا الحدث (عوامل التشغيل القابلة للتثبيت فقط) 4034124084959907503
`user`	كائن `User`، يمثّل المستخدم النشط، إذا كان متاحًا (حسب مجموعة معقّدة من قيود الأمان). amin@example.com
`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', 'amin@example.com', 'Bob', '27', 'Bill', '28', 'Susan', '25']

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

تسمح المشغّلات لتطبيق "مستندات Google" بالاستجابة عندما يفتح المستخدم مستندًا.

فتح (بسيط وقابل للتثبيت)
`authMode`	قيمة من التعداد `ScriptApp.AuthMode` LIMITED
`source`	كائن `Document` يمثّل ملف "مستندات Google" الذي يرتبط به النص البرمجي. Document
`triggerUid`	معرّف عامل التشغيل الذي أدّى إلى إنشاء هذا الحدث (عوامل التشغيل القابلة للتثبيت فقط) 4034124084959907503
`user`	كائن `User`، يمثّل المستخدم النشط، إذا كان متاحًا (حسب مجموعة معقّدة من قيود الأمان). amin@example.com

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

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

فتح (بسيط)
`authMode`	قيمة من التعداد `ScriptApp.AuthMode` LIMITED
`source`	كائن `Presentation` يمثّل ملف "العروض التقديمية من Google" الذي يرتبط به النص البرمجي. Presentation
`user`	كائن `User`، يمثّل المستخدم النشط، إذا كان متاحًا (حسب مجموعة معقّدة من قيود الأمان). amin@example.com

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

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

فتح * (بسيط وقابل للتثبيت)
`authMode`	قيمة من التعداد `ScriptApp.AuthMode` LIMITED
`source`	كائن `Form` يمثّل ملف النماذج الذي يرتبط به النص البرمجي. Form
`triggerUid`	معرّف عامل التشغيل الذي أدّى إلى إنشاء هذا الحدث (عوامل التشغيل القابلة للتثبيت فقط) 4034124084959907503
`user`	كائن `User`، يمثّل المستخدم النشط، إذا كان متاحًا (حسب مجموعة معقّدة من قيود الأمان). amin@example.com

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

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

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

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

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

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

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

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

EventUpdated (قابلة للتثبيت)
`authMode`	قيمة من التعداد `ScriptApp.AuthMode`. FULL
`calendarId`	المعرّف السلسلي للتقويم الذي تمّ فيه تعديل الحدث susan@example.com
`triggerUid`	معرّف عامل التشغيل الذي أدّى إلى إنشاء هذا الحدث. 4034124084959907503

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

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

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

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

للتعرّف على عناصر الأحداث في 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

عناصر الأحداث تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

فتح

تغيير

تعديل

إرسال النموذج