إجراءات الإضافات

توفّر إجراءات الإضافات سلوكًا تفاعليًا للويدجت. من خلال إنشاء إجراء، يمكنك تحديد ما يحدث عندما يختار المستخدم أداة أو يحدّثها.

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

يمكنك ضبط تطبيق مصغّر باستخدام Action باتّباع الخطوات العامة التالية:

  1. أنشئ العنصر Action، مع تحديد دالة رد الاتصال التي يجب تنفيذها مع أي مَعلمات تتطلّبها.
  2. استدعِ دالة معالجة الأداة المناسبة في الأداة باستخدام العنصر Action.
  3. نفِّذ دالة رد الاتصال لتفعيل السلوك المطلوب.

وظائف معالجة التطبيقات المصغّرة

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

يسرد الجدول التالي أنواع المعالجات المختلفة للعناصر ويوضّح العناصر التي يتم استخدامها معها:

دالة المعالجة إجراءات التشغيل التطبيقات المصغّرة السارية الوصف
setOnChangeAction() تتغيّر قيمة التطبيق المصغّر DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker 		تضبط هذه السمة Action الذي ينفّذ دالة Apps Script عندما يفقد العنصر واجهة المستخدم تركيزه، مثلما يحدث عندما يُدخل المستخدم نصًا في حقل إدخال ويضغط على مفتاح Enter. يمرّر المعالج تلقائيًا كائن حدث إلى الدالة التي يستدعيها. يمكنك إدراج معلومات مَعلمات إضافية في عنصر الحدث هذا في حال اختيار ذلك.
setOnClickAction() ينقر المستخدم على التطبيق المصغّر CardAction
Image
ImageButton
DecoratedText
TextButton 		تضبط هذه السمة Action الذي ينفِّذ دالة Apps Script عندما ينقر المستخدم على الأداة. يمرّر المعالج تلقائيًا كائن حدث إلى الدالة التي يستدعيها. يمكنك إدراج معلومات المَعلمات الاختيارية في عنصر الحدث هذا.
setComposeAction() ينقر المستخدم على التطبيق المصغّر CardAction
Image
ImageButton
DecoratedText
TextButton 		خاصة بـ Gmail تضبط هذه السمة Action التي تنشئ مسودة رسالة إلكترونية، ثم تعرض هذه المسودة للمستخدم في نافذة إنشاء في واجهة مستخدم Gmail. يمكنك إنشاء المسودة كرسالة جديدة أو كرد على الرسالة المفتوحة في Gmail. عندما يستدعي المعالج دالة رد الاتصال الخاصة بإنشاء المسودّة، يمرّر عنصر حدث إلى دالة رد الاتصال. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة إنشاء مسودات رسائل.
setOnClickOpenLinkAction() ينقر المستخدم على التطبيق المصغّر CardAction
Image
ImageButton
DecoratedText
TextButton 		تضبط هذه السمة Action لفتح عنوان URL عندما ي��قر المستخدم على الأداة. استخدِم هذا المعالج عندما تحتاج إلى إنشاء عنوان URL أو عندما يجب تنفيذ إجراءات أخرى قبل فتح الرابط، وإلا سيكون من الأسهل عادةً استخدام setOpenLink(). يمكنك فتح عنوان URL في نافذة جديدة فقط. عند إغلاقها، يمكنك إعادة تحميل الإضافة في واجهة المستخدم.
setOpenLink() ينقر المستخدم على التطبيق المصغّر CardAction
Image
ImageButton
DecoratedText
TextButton 		يفتح عنوان URL مباشرةً عندما ينقر المستخدم على الأداة. استخدِم أداة المعالجة هذه عندما تعرف عنوان URL وتحتاج فقط إلى فتحه، وإلا استخدِم setOnClickOpenLinkAction(). يمكنك فتح عنوان URL في نافذة جديدة أو في نافذة منبثقة. عند إغلاقها، يمكنك إعادة تحميل الإضافة في واجهة المستخدم.
setSuggestionsAction() يدخل المستخدم نصًا في حقل إدخال TextInput تضبط هذه السمة Action الذي ينفّذ دالة Apps Script عندما يُدخل المستخدم نصًا في أداة إدخال نص. يمرّر المعالج تلقائيًا كائن حدث إلى الدالة التي يستدعيها. يمكنك الاطّلاع على اقتراحات الإكمال التلقائي لإدخالات النصوص لمزيد من التفاصيل.

دوال رد الاتصال

يتم تنفيذ دوال رد الاتصال عندما يتم تشغيل Action. بما أنّ دوال معاودة الاتصال هي دوال في Apps Script، يمكنك أن تجعلها تنفّذ أي إجراء يمكن أن تنفّذه أي دالة نص برمجي أخرى تقريبًا.

.

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

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

الإجراء الذي تمت محاولة تنفيذه يجب أن تعرض دالة رد الاتصال
التنقّل بين البطاقات ActionResponse
عرض Notification ActionResponse
فتح رابط باستخدام setOnClickOpenLinkAction() ActionResponse
عرض اقتراحات الإكمال التلقائي SuggestionResponse
استخدام إجراء عالمي UniversalActionResponse
الإجراءات الأخرى Nothing

إجراءات لتطبيقات Google Workspace المض��فة

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

عناصر أحداث الإجراءات

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

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

راجِع عناصر الحدث للحصول على شرح كامل لبنية عنصر الحدث.