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

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

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

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

ほとんどの場合、以下の一般的な手順に沿って、選択または更新されたときにウィジェットが特定のアクションを実行するように構成できます。

  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() を使用する場合は、OpenLink オブジェクトを指定して開く URL を定義する必要があります。また、このオブジェクトで OpenAs 列挙型と OnClose 列挙型を使用して開閉動作を指定することもできます。

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

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

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