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

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