インタラクティブなカードの作成

ほとんどのアドオンでは、データを表示するだけでなく、ユーザーが情報を入力する必要があります。カードベースのアドオンを作成する場合は、ボタン、ツールバー メニュー項目、チェックボックスなどのインタラクティブなウィジェットを使用して、アドオンに必要なデータをユーザーに尋ねたり、他のインタラクション コントロールを提供したりできます。

ウィジェットにアクションを追加する

ほとんどの場合、ウィジェットをインタラクティブにするには、特定のアクションにリンクし、必要な動作をコールバック関数に実装します。詳しくは、アドオン アクションをご覧ください。

ほとんどの場合、選択または更新時に特定のアクションを実行するようにウィジェットを構成するには、次の一般的な手順を行います。

  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!
  }

効果的なインタラクションを設計する

インタラクティブ カードを設計する際は、次の点に注意してください。

  • 通常、インタラクティブ ウィジェットには、動作を定義するハンドラ メソッドが 1 つ以上必要です。

  • URL があり、タブで開くだけの場合は、setOpenLink() ウィジェット ハンドラ関数を使用します。これにより、Action オブジェクトとコールバック関数を定義する必要がなくなります。最初に URL をビルドする必要がある場合や、URL を開く前に他の追加の手順を実行する必要がある場合は、Action を定義し、代わりに setOnClickOpenLinkAction() を使用します。

  • setOpenLink() または setOnClickOpenLinkAction() ウィジェット ハンドラ関数を使用する場合は、開く URL を定義する OpenLink オブジェクトを指定する必要があります。このオブジェクトを使用して、OpenAs 列挙型と OnClose 列挙型を使用して開閉動作を指定することもできます。

  • 複数のウィジェットで同じ Action オブジェクトを使用できます。ただし、コールバック関数に異なるパラメータを指定する場合は、異なる Action オブジェクトを定義する必要があります。

  • コールバック関数はシンプルにします。アドオンの応答性を維持するため、カード サービスではコールバック関数の実行時間を最大 30 秒に制限しています。実行にそれ以上時間がかかると、アドオン UI が Action に応答してカードの表示を適切に更新しない可能性があります。

  • ユーザーがアドオン UI を操作した結果、サードパーティ バックエンドのデータステータスが変更された場合は、アドオンで「state changed」ビットを true に設定して、既存のクライアントサイド キャッシュを消去することをおすすめします。詳細については、ActionResponseBuilder.setStateChanged() メソッドの説明をご覧ください。