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

توضّح هذه الصفحة بنية عناصر أحداث إضافات Google Workspace.

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

تستخدم إضافات Google Workspace عناصر الأحداث في المواضع التالية:

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

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

• الإجراءات التي تفعّل القاعدة حسب السياق: يوفّر كل تطبيق مضيف مجموعة مختلفة من المشغّلات السياقية التي يتم تفعيلها عندما يدخل المستخدم في سياق معيّن:

  • عندما يكون المستخدم:
    • فتح رسالة
    • يكتب رسالة
    • يفتح حدثًا.
  • يوفّر Google Drive عاملاً مشغِّلاً سياقيًا عندما يختار المستخدم ملفات Drive.

  عندما يتم تشغيل مشغّل سياقي، يستدعي التطبيق المضيف الدالة runFunction المدرَجة في بيان الإضافة، ويمرّر إليها كائن حدث كمعلَمة. تحتوي عناصر الحدث التي يتم إنشاؤها عند تنشيط المشغّلات السياقية على جميع الحقول المضمّنة في عناصر حدث مشغّل الصفحة الرئيسية، بالإضافة إلى الحقول التي تحتوي على معلومات سياقية.

• إجراءات التطبيق المصغّر توفّر عناصر الأحداث تفاعلاً مع الأدوات، وذلك باستخدام نموذج الإجراء نفسه الذي تستخدمه إضافات Gmail. تستخدم إضافات Google Workspace دوال معالجة الأدوات نفسها، وكائنات Action، وردود الإجراءات. في إضافات Google Workspace، تتضمّن عناصر حدث الإجراء المزيد من المعلومات التي يمكن أن تستند إليها دالّة رد الاتصال.

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

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

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

بنية عنصر الحدث

يوضّح الجدول التالي البنية ذات المستوى الأعلى لعناصر أحداث إضافات Google Workspace. يتضمّن البنية حقل commonEventObject على المستوى الأعلى للمعلومات المستقلة عن المضيف. يمكن أن يحتوي كل عنصر حدث أيضًا على أحد الحقول التالية على المستوى الأعلى الخاصة بالمضيف، والتي يحدّدها التطبيق المضيف النشط: gmailEventObject أو calendarEventObject أو driveEventObject.

لضمان التوافق مع الإصدارات القديمة، تتضمّن عناصر أحداث إضافات Google Workspace الحقول الأصلية المستخدَمة في عناصر أحداث إجراءات إضافات Gmail. تندرج هذه الحقول ضمن "حقول الإضافات الأصلية في Gmail"، وهي ليست جزءًا من commonEventObject.

تم إيقاف حقول إضافة ميزات Gmail الأصلية نهائيًا. عند تطوير إضافة Google Workspace أو نقلها، استخدِم بنية عنصر الحدث الأحدث بدلاً من ذلك. وقد تتم إزالة هذه الحقول في تحديث مستقبلي.

عنصر الحدث الشائع

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

بالإضافة إلى المشغّلات السياقية والمشغّلات على الصفحة الرئيسية، تنشئ الإضافات عناصر الأحداث وتمرّرها إلى وظائف معاودة الاتصال الخاصة بالإجراءات عندما يتفاعل المستخدم مع التطبيقات المصغّرة. يمكن أن تستعلم دالّة رد الاتصال الخاصة بالإضافة عن عنصر الحدث الشائع لتحديد محتوى الأدوات المفتوحة في برنامج المستخدم. على سبيل المثال، يمكن للإضافة تحديد موقع النص الذي أدخله المستخدم في أداة TextInput ضمن عنصر eventObject.commentEventObject.formInputs.

مدخلات نموذج أداة اختيار التاريخ والوقت

يمكن لدوال ردّ الاتصال الخاصة بالإجراءات تلقّي قيم الأداة الحالية في الحقل commonEventObject.formInputs. ويشمل ذلك قيم التاريخ أو الوقت التي يختارها المستخدم في أدوات اختيار التاريخ أو الوقت. يختلف هيكل المعلومات حسب ما إذا تم ضبط الأداة على أنّها أداة اختيار التاريخ والوقت أو أداة اختيار التاريخ فقط أو أداة اختيار الوقت فقط. يتم توضيح الاختلافات البنيوية في الجدول التالي:

عنصر حدث المحادثة

عنصر حدث Chat هو جزء من عنصر الحدث العام الذي يتضمّن معلومات حول تفاعلات المستخدم مع تطبيق Chat، ولا يظهر إلا في عنصر الحدث إذا كان الإضافة توسّع نطاق Google Chat.

الحمولة

استنادًا إلى نوع التفاعل مع تطبيق Chat، يحتوي الحدث على حمولة تتضمّن مرجعًا واحدًا أو أكثر من مراجع Chat API.

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}