ساخت کارت های تعاملی

بیشتر افزونه‌ها، علاوه بر ارائه داده‌ها، از کاربر می‌خواهند که اطلاعات را وارد کند. وقتی یک افزونه مبتنی بر کارت می‌سازید، می‌توانید از ویجت‌های تعاملی مانند دکمه‌ها، آیتم‌های منوی نوار ابزار یا کادرهای انتخاب استفاده کنید تا از کاربر داده‌هایی را که افزونه شما به آنها نیاز دارد، درخواست کنید یا کنترل‌های تعاملی دیگری را ارائه دهید.

افزودن اقدامات به ابزارک‌ها

در بیشتر موارد، شما با پیوند دادن ویجت‌ها به اقدامات خاص و پیاده‌سازی رفتار مورد نیاز در یک تابع فراخوانی، آنها را تعاملی می‌کنید. برای جزئیات بیشتر به اقدامات افزونه مراجعه کنید.

در بیشتر موارد، می‌توانید این رویه کلی را برای پیکربندی یک ویجت جهت انجام یک اقدام خاص هنگام انتخاب یا به‌روزرسانی دنبال کنید:

1. یک شیء Action ایجاد کنید، و تابع فراخوانی که باید اجرا شود را به همراه پارامترهای مورد نیاز مشخص کنید.
2. با فراخوانی تابع مدیریت ویجت مربوطه، ویجت را به اکشن ( Action لینک کنید.
3. تابع فراخوانی (callback) را برای اجرای رفتار مورد نیاز پیاده‌سازی کنید.

مثال

مثال زیر دکمه‌ای را تنظیم می‌کند که پس از کلیک، یک اعلان به کاربر نمایش می‌دهد. کلیک، تابع فراخوانی 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!
  }

طراحی تعاملات مؤثر

هنگام طراحی کارت‌های تعاملی، موارد زیر را در نظر داشته باشید:

• ویجت‌های تعاملی معمولاً حداقل به یک متد handler برای تعریف رفتار خود نیاز دارند.

• وقتی یک URL دارید و می‌خواهید آن را در یک تب باز کنید، از تابع کنترل‌کننده ویجت setOpenLink() استفاده کنید. این کار از نیاز به تعریف یک شیء Action و تابع فراخوانی (callback) جلوگیری می‌کند. اگر نیاز دارید که ابتدا URL را بسازید، یا قبل از باز کردن URL مراحل اضافی دیگری را انجام دهید، یک Action تعریف کنید و به جای آن از setOnClickOpenLinkAction() استفاده کنید.

• هنگام استفاده از توابع کنترل ویجت setOpenLink() یا setOnClickOpenLinkAction() ، باید یک شیء OpenLink برای تعریف URL مورد نظر برای باز شدن ارائه دهید. همچنین می‌توانید از این شیء برای تعیین رفتار باز و بسته شدن با استفاده از enumهای OpenAs و OnClose استفاده کنید.

• این امکان وجود دارد که بیش از یک ویجت از یک شیء Action استفاده کنند. با این حال، اگر می‌خواهید پارامترهای مختلفی را به تابع callback ارائه دهید، باید اشیاء Action متفاوتی تعریف کنید.

• توابع فراخوانی خود را ساده نگه دارید. برای اینکه افزونه‌ها واکنش‌گرا باشند، سرویس Card زمان اجرای توابع فراخوانی را حداکثر به 30 ثانیه محدود می‌کند. اگر اجرا بیش از این طول بکشد، رابط کاربری افزونه شما ممکن است نمایش کارت خود را در پاسخ به Action به درستی به‌روزرسانی نکند.

• اگر وضعیت داده‌ها در یک backend شخص ثالث در نتیجه تعامل کاربر با رابط کاربری افزونه شما تغییر کند، توصیه می‌شود افزونه بیت 'state changed' را روی true تنظیم کند تا هرگونه حافظه پنهان موجود در سمت کلاینت پاک شود. برای جزئیات بیشتر به توضیحات متد ActionResponseBuilder.setStateChanged() مراجعه کنید.