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

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

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

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

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

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() widget handler عندما يكون لديك عنوان URL وتريد فتحه في علامة تبويب فقط. ويؤدي ذلك إلى تجنُّب الحاجة إلى تحديد كائن Action ودالة ردّ الاتصال. إذا كنت بحاجة إلى إنشاء عنوان URL أولاً، أو اتّخاذ أي خطوات إضافية أخرى قبل فتح عنوان URL، حدِّد Action واستخدِم setOnClickOpenLinkAction() بدلاً من ذلك.

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

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

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

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