كائنات الأحداث

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

فتح

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

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

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

للمزامنة مع التقويم في برمجة التطبيقات، يمكنك إجراء الخطوات التالية:

  1. مكّن خدمة التقويم المتقدمة لمشروع النص البرمجي. ولا تُعد خدمة "تقويم 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

أحداث الإضافة

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

تثبيت

(بسيط)
authMode

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

FULL

الأحداث المستندة إلى الوقت

المشغّلات المستندة إلى الوقت (تُسمّى أيضًا مشغلات الساعة) تتيح تنفيذ النصوص البرمجية في وقت معيّن أو على فترة زمنية متكرّرة.

مستند إلى الوقت (قابل للتثبيت)
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