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

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

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

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

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

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