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

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

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

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

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

.

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

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

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

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

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

• إجراءات التقويم
• إجراءات تتعلّق بالمحادثة
• إجراءات Drive
• إجراءات Gmail
• إجراءات المحرّر

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

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

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

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

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

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

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