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

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

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

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

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

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