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

تتيح المشغِّلات البسيطة والمشغِّلات القابلة للتثبيت لتطبيق 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());
}

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

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

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

فتح

(بسيطة وقابلة للتثبيت)
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

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

(قابل للتثبيت)
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، يمثّل ملف "نماذج Google" المرتبط بالنص البرمجي.

Form
triggerUid

رقم تعريف العامل المشغِّل الذي أدّى إلى حدوث هذا الحدث (عوامل التشغيل القابلة للتثبيت فقط)

4034124084959907503
user

عنصر User، يمثّل المستخدم النشط، في حال توفّره (حسب مجموعة معقدة من قيود الأمان).

amin@example.com

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

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

(قابل للتثبيت)
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 الذي حفظته لهذا التقويم باستخدام القيمة التي تم عرضها بواسطة طلب المزامنة المتزايدة. يؤدي ذلك إلى فرض إجراء عملية المزامنة التالية لمحاولة عرض أحدث التغييرات فقط.

EventUpdated

(قابل للتثبيت)
authMode

قيمة من التعداد ScriptApp.AuthMode 

FULL
calendarId

رقم تعريف السلسلة للتقويم الذي حدث فيه تعديل الحدث.

susan@example.com
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