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

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

افزودن اقدامات به ویجت ها

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

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

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

مثال

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

تعاملات موثر طراحی کنید

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

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

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

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

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

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

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