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

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

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

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

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

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() لمعرفة المزيد من التفاصيل.