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

تتيح المشغّلات البسيطة والمشغّلات القابلة للتثبيت لخدمة Apps Script تشغيل دالة تلقائيًا عند وقوع حدث معيّن. عندما يتم تشغيل مشغّل، تمرِّر "برمجة تطبيقات 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 يمثّل المستخدم النشط، إذا كان متاحًا (حسب مجموعة معقّدة من قيود الأمان). [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".

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

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