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

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

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

إضافة إجراءات إلى الأدوات

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

في معظم الحالات، يمكنك اتباع هذا الإجراء العام لتهيئة أداة لاتخاذ إجراء معين عند تحديدها أو تحديثها:

  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)
            .setType(CardService.NotificationType.INFO))
        .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() للحصول على تفاصيل إضافية.