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

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

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

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

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

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() ووصف الطريقة للحصول على تفاصيل إضافية.