إنشاء بطاقات تفاعلية

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

إضافة إجراءات إلى التطبيقات المصغّرة

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

في معظم الحالات، يمكنك اتّباع هذا الإجراء العام لإعداد تطبيق مصغّر لاتخاذ إجراء محدّد عند اختياره أو تعديله:

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

مثال

يقوم المثال التالي بتعيين زر يعرض إشعارًا للمستخدم بعد النقر فوقه. تؤدي النقرة إلى تشغيل دالة استدعاء notifyUser() باستخدام وسيطة تحدِّد نص الإشعار. يؤدي عرض رمز ActionResponse مضمَّن إلى ظهور إشعار.

  /**
   * Build a simple card with a button that sends a notification.
   * @return {Card}
   */
  function buildSimpleCard() {
    var buttonAction = CardService.newAction()
        .setFunctionName('notifyUser')
        .setParameters({'notifyText': 'Button clicked!'});
    var button = CardService.newTextButton()
        .setText('Notify')
        .setOnClickAction(buttonAction);

    // ...continue creating widgets, then create a Card object
    // to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Constructs a
   * notification action response and returns it.
   * @param {Object} e the action event object
   * @return {ActionResponse}
   */
  function notifyUser(e) {
    var parameters = e.parameters;
    var notificationText = parameters['notifyText'];
    return CardService.newActionResponseBuilder()
        .setNotification(CardService.newNotification()
            .setText(notificationText)
        .build();      // Don't forget to build the response!
  }

تصميم تفاعلات فعالة

عند تصميم بطاقات تفاعلية، ضع ما يلي في الاعتبار:

• عادةً ما تحتاج التطبيقات المصغّرة التفاعلية إلى طريقة معالج واحدة على الأقل لتحديد سلوكها.

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

• عند استخدام دالتَي معالج الأداة setOpenLink() أو setOnClickOpenLinkAction()، عليك توفير كائن OpenLink لتحديد عنوان URL المطلوب فتحه. يمكنك أيضًا استخدام هذا الكائن لتحديد سلوك الفتح والإغلاق باستخدام التعدادَين OpenAs وOnClose.

• من الممكن لأكثر من تطبيق مصغّر واحد استخدام الكائن Action نفسه. ومع ذلك، عليك تحديد كائنات Action مختلفة إذا كنت تريد توفير مَعلمات مختلفة لدالة استدعاء الدالة.

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

• إذا تغيّرت حالة البيانات على خلفية تابعة لجهة خارجية نتيجة تفاعل أحد المستخدمين مع واجهة مستخدم الإضافة، نقترح ضبط البت للإضافة "تم تغيير الحالة" على true بحيث يتم محو أي ذاكرة تخزين مؤقت حالية من جهة العميل. اطّلِع على وصف طريقة ActionResponseBuilder.setStateChanged() للحصول على تفاصيل إضافية.