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

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

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

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

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

  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)
            .setType(CardService.NotificationType.INFO))
        .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 秒の実行時間に制限します。この実行に時間がかかる場合、Action に応じてアドオン UI でカードの表示が正しく更新されないことがあります。

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