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

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

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

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

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

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

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

  • يوفّر Gmail مشغّلاً سياقيًا عند فتح المستخدم رسالة، ومشغّلاً آخر عند إنشاء المستخدم رسالة.
  • يوفّر "تقويم Google" عامل تشغيل سياقيًا عندما يفتح المستخدم حدثًا.
  • يوفّر 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"، ويتم إعادة إنتاج المعلومات الواردة في هذه الحقول في بنية عنصر جديدة.

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

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

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