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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

راجِع كائنات الحدث للاطّلاع على شرحًا لبنية كائن الحدث.