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

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

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

أحداث "جداول بيانات 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" عند تحديث أحداث تقويم المستخدم (سواء تم إنشاؤها أو تعديلها أو حذفها).

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

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

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

تم تعديل الحدث.

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