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

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

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

اضبط أداة مع Action باستخدام هذه العملية العامة:

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

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

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

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

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

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

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

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

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

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

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