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

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

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

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

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

  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 秒の実行時間に制限します。実行にそれ以上かかる場合、アドオン UI が Action に応じてカード表示を適切に更新しないことがあります。

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