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

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

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

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

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

ملاحظة: لا تخلط بين عناصر Action وعناصر CardAction. عناصر CardAction هي عناصر قائمة رؤوس البطاقات، في حين تحدّد عناصر Action الاستجابات لتفاعلات المستخدم مع واجهة المستخدم.

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

لربط التطبيق المصغّر بعنصر 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، يمكنك استخدامها للقيام بكل ما يمكن لأيّ دالة نصية أخرى فعله تقريبًا.

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

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

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

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

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

• إجراءات التقويم
• إجراءات Drive
• إجراءات Gmail
• إجراءات المحرِّر

ملاحظة: عند استخدام فئات "أداة إنشاء الردود"، احرص على استدعاء build() ل إنشاء عناصر الردود. يؤدي عدم إجراء ذلك إلى ظهور خطأ.

ملاحظة: يتم تعريف الإجراءات الشاملة في بيان المشروع ولا تحتاج إلى عناصر Action ، ولكن يجب أن تعرِض دوالّ الاستدعاء الخاصة بها UniversalActionResponse.

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

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

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

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

ملاحظة: كانت إضافات Gmail تستخدِم نسخة مبسّطة من بنية عنصر الحدث هذه، وقد تم إيقافها نهائيًا الآن. للحفاظ على التوافق مع الإصدارات القديمة، لا تزال جميع حقول ملفّات تعريف حدث تطبيقات Gmail الإضافية الأصلية مضمّنة في بنية ملفّ تعريف حدث الجديدة (راجِع بنية ملفّ تعريف الحدث). ومع ذلك، تتم إعادة إنتاج المعلومات نفسها في البنى الفرعية للعنصرين الحدث الشائع وحدث Gmail. إذا كنت بصدد ترقية إضافة Gmail إلى إضافة Google Workspace، عليك تعديل الرمز البرمجي لاستخدام حقول عناصر الحدث المعدَّلة، وسيتم في النهاية إزالة حقول عناصر الحدث الأصلية في Gmail.