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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

دوال معالج الأدوات

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

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

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

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

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

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

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

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