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

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

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

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

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

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