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

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

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

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

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

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

وظائف معالج الأدوات

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

يسرد الجدول التالي أنواع المعالجات المختلفة للأدوات والتطبيقات المصغّرة التي تستخدمها:

وظيفة المعالج	إجراءات التشغيل	التطبيقات المصغّرة التي تنطبق	الوصف
setOnChangeAction()	تغيير قيمة التطبيق المصغّر	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	تضبط هذه السياسة Action التي تنفّذ وظيفة "برمجة تطبيقات Google" عندما يفقد التطبيق المصغّر التركيز، مثلاً عندما يُدخِل المستخدم نصًا في أحد الإدخالات ويضغط على مفتاح Enter. ويعمل المعالج تلقائيًا على تمرير كائن الحدث إلى الدالة التي يستدعيها. يمكنك إدراج معلومات مَعلمة إضافية في كائن الحدث هذا إذا أردت ذلك.
setOnClickAction()	ينقر المستخدم على التطبيق المصغّر.	CardAction Image ImageButton DecoratedText TextButton	تضبط هذه السياسة Action يتم من خلالها تنفيذ وظيفة "برمجة تطبيقات Google" عندما ينقر المستخدم على الأداة. ويعمل المعالج تلقائيًا على تمرير كائن الحدث إلى الدالة التي يستدعيها. يمكنك إدراج معلومات مَعلمة اختيارية في كائن الحدث هذا.
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 التي تنفّذ دالة "برمجة تطبيقات Google" عندما يُدخِل المستخدم نصًا في أداة إدخال النص. يمرِّر المعالج تلقائيًا كائن حدث إلى الدالة التي يستدعيها. راجِع اقتراحات الإكمال التلقائي لإدخالات النص للحصول على مزيد من التفاصيل.

دوال معاودة الاتصال

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

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

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

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

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

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

• إجراءات "تقويم Google"
• الحث على اتخاذ إجراءات
• إجراءات Gmail
• إجراءات المحرِّر

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

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

كائنات أحداث الإجراءات

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

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

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

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