インタラクティブなカードまたはダイアログを設計する

このページでは、ボタンのクリックや情報の送信などでユーザーが Google Chat アプリを操作できるように、カードやダイアログ メッセージにウィジェットと UI 要素を追加する方法について説明します。

カードビルダーでカードをデザインしてプレビューする。

前提条件

ボタンを追加する

ButtonList ウィジェットに一連のボタンが表示されます。ボタンには、テキスト、アイコン、またはその両方を表示できます。各 Button は、ユーザーがボタンをクリックしたときに発生する OnClick アクションをサポートしています。次に例を示します。

• OpenLink でハイパーリンクを開き、ユーザーに追加情報を提供します。
• API の呼び出しなど、カスタム関数を実行する action を実行します。

ユーザー補助機能を念頭に置いて、ボタンは代替テキストをサポートしています。

カスタム関数を実行するボタンを追加する

次のカードは、2 つのボタンを持つ ButtonList ウィジェットで構成されています。1 つのボタンを押すと、Google Chat デベロッパー向けドキュメントが新しいタブで開きます。もう 1 つのボタンは、goToView() というカスタム関数を実行し、viewType="BIRD EYE VIEW" パラメータを渡します。

カスタムカラーのボタンと無効化されたボタンを追加する

ユーザーがボタンをクリックできないようにするには、"disabled": "true" を設定します。

以下は、2 つのボタンを持つ ButtonList ウィジェットで構成されるカードを示しています。一方のボタンでは、Color フィールドを使用してボタンの背景色をカスタマイズします。もう 1 つのボタンは Disabled フィールドで無効になり、ユーザーはボタンをクリックして関数を実行できなくなります。

アイコン付きのボタンを追加する

以下は、ButtonList ウィジェットと 2 つのアイコン Button ウィジェットで構成されるカードを示しています。1 つのボタンで、knownIcon フィールドを使用して Google Chat の組み込みメールアイコンを表示します。もう 1 つのボタンは、iconUrl フィールドを使用してカスタム アイコン ウィジェットを表示します。

アイコンとテキストを含むボタンを追加する

以下に、ユーザーにメールの送信を求める ButtonList ウィジェットで構成されるカードを示します。最初のボタンにはメールアイコンが表示され、2 番目のボタンにはテキストが表示されます。ユーザーは、アイコンまたはテキストボタンをクリックして、sendEmail 関数を実行できます。

選択可能な UI 要素を追加する

SelectionInput ウィジェットには、チェックボックス、ラジオボタン、スイッチ、プルダウン メニューなど、選択可能なアイテムのセットが用意されています。このウィジェットを使用すると、定義された標準化されたデータをユーザーから収集できます。未定義のデータをユーザーから収集するには、代わりに TextInput ウィジェットを使用します。

SelectionInput ウィジェットは、ユーザーによるユニフォーム データの入力に役立つ候補と、選択入力フィールドで変更（ユーザーによるアイテムの選択や選択解除など）が発生したときに実行される変更時のアクション（Actions）をサポートしています。

チャットアプリは、選択されたアイテムの値を受信して処理できます。フォーム入力の操作について詳しくは、フォームデータを受信するをご覧ください。

このセクションでは、SelectionInput ウィジェットを使用するカードの例を示します。この例では、さまざまな種類のセクション入力を使用します。

• チェックボックス
• ラジオボタン
• スイッチ
• プルダウン メニュー
• 複数選択メニュー

チェックボックスを追加する

以下は、チェックボックスを使用する SelectionInput ウィジェットで、連絡先がプロフェッショナル、プライベート、またはその両方であるかを指定するようにユーザーに求めるダイアログを表示します。

ラジオボタンを追加する

以下は、ラジオボタンを使用する SelectionInput ウィジェットで、連絡先がプロフェッショナルか個人用かを指定するようにユーザーに求めるダイアログを表示します。

スイッチを追加する

以下は、スイッチを使用する SelectionInput ウィジェットで、連絡先がプロフェッショナルか個人用か、その両方かを指定するようにユーザーに求めるダイアログを表示します。

プルダウン メニューを追加

プルダウン メニューを使用する SelectionInput ウィジェットで、連絡先がプロフェッショナルか個人用かを指定するようにユーザーに求めるダイアログを以下に示します。

複数選択メニューを追加する

以下は、複数選択メニューから連絡先を選択するようユーザーに求めるダイアログを表示します。

複数選択メニューにデータソースを使用する

次のセクションでは、複数選択メニューを使用して、Google Workspace アプリケーションや外部データソースなどの動的ソースからデータを収集する方法について説明します。

Google Workspace のデータソース

複数選択メニューの項目は、Google Workspace の次のデータソースから入力できます。

• Google Workspace ユーザー: 同じ Google Workspace 組織内のユーザーにのみ入力できます。
• Chat スペース: 複数選択メニューで項目を入力するユーザーは、自分の Google Workspace 組織内で自身が属しているスペースのみを表示および選択できます。

Google Workspace データソースを使用するには、platformDataSource フィールドを指定します。他の選択入力タイプとは異なり、SectionItem オブジェクトは省略します。これらの選択アイテムは Google Workspace から動的に取得されるためです。

次のコードは、Google Workspace ユーザーの複数選択メニューを示しています。 ユーザーを入力するには、選択入力で commonDataSource を USER に設定します。

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

次のコードは、Chat スペースの複数選択メニューを示しています。スペースを入力するには、選択入力で hostAppDataSource フィールドを指定します。また、複数選択メニューでは、defaultToCurrentSpace が true に設定され、現在のスペースがメニューのデフォルト選択になります。

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Google Workspace の外部にあるデータソース

複数選択メニューでは、サードパーティまたは外部のデータソースからアイテムを入力することもできます。たとえば、複数選択メニューを使用すると、ユーザーが顧客管理（CRM）システムから見込み顧客のリストから選択しやすくなります。

外部データソースを使用するには、externalDataSource フィールドを使用して、データソースからアイテムを返す関数を指定します。

外部データソースへのリクエストを減らすために、ユーザーがメニューを入力する前に複数選択メニューに表示される候補項目を含めることができます。たとえば、ユーザーの最近検索した連絡先を入力できます。外部データソースから提案されたアイテムを入力するには、SelectionItem オブジェクトを指定します。

次のコードは、ユーザーの外部連絡先セットから項目の複数選択メニューを表示します。メニューにはデフォルトで 1 つの連絡先が表示され、getContacts 関数を実行して、外部データソースからアイテムを取得してデータを入力します。

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 2,
    "externalDataSource": {
      "function": "getContacts"
    },
    "items": [
      {
        "text": "Contact 3",
        "value": "contact-3",
        "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
        "bottomText": "Contact three description",
        "selected": false
      }
    ]
  }
}

外部データソースの場合は、複数選択メニューでユーザーが入力を開始した項目をオートコンプリートすることもできます。たとえば、米国の都市が入力されるメニューで、ユーザーが Atl の入力を開始した場合、ユーザーが入力を完了する前に Chat アプリで Atlanta を自動候補として提示できます。最大 100 件の項目をオートコンプリートできます。

アイテムをオートコンプリートするには、外部データソースに対してクエリを実行し、ユーザーが複数選択メニューに入力するたびにアイテムを返す関数を作成します。この関数は次のことを行う必要があります。

• メニューのユーザー操作を表すイベント オブジェクトを渡します。
• インタラクション イベントの invokedFunction 値が externalDataSource フィールドの関数と一致することを確認します。
• 関数が一致した場合、外部データソースから提案されたアイテムを返します。ユーザーの入力内容に基づいてアイテムを提案するには、autocomplete_widget_query キーの値を取得します。この値は、ユーザーがメニューで入力する内容を表します。

次のコードは、外部データリソースのアイテムをオートコンプリートします。上記の例を使用すると、Chat アプリは getContacts 関数がトリガーされたタイミングに基づいてアイテムを提案します。

/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

ユーザーがテキストを入力できるフィールドを追加する

TextInput ウィジェットには、ユーザーがテキストを入力できるフィールドがあります。このウィジェットは、ユーザーがユニフォーム データを入力する際に役立つ提案と、変更時のアクション（ユーザーによるテキストの追加や削除など、テキスト入力フィールドで変更が発生したときに実行される Actions）をサポートしています。

ユーザーから抽象的なデータや未知のデータを収集する必要がある場合は、この TextInput ウィジェットを使用します。定義済みのデータを収集するには、代わりに SelectionInput ウィジェットを使用します。

ユーザーが入力したテキストを処理するには、フォームデータを受信するをご覧ください。

TextInput ウィジェットで構成されるカードを以下に示します。

ユーザーが日時を選択できるようにする

DateTimePicker ウィジェットを使用すると、ユーザーは日付、時刻、またはその両方を入力できます。または、選択ツールを使用して日付と時刻を選択することもできます。ユーザーが無効な日時を入力した場合、選択ツールにエラーが表示され、ユーザーに情報を正しく入力するよう促します。

ユーザーが入力した日付と時刻の値を処理する方法については、フォームデータを受信するをご覧ください。

3 種類の DateTimePicker ウィジェットで構成されるカードを以下に示します。

トラブルシューティング

Google Chat アプリまたはカードからエラーが返されると、Chat インターフェースに「エラーが発生しました」または「リクエストを処理できません」というメッセージが表示されます。Chat UI にエラー メッセージが表示されないにもかかわらず、Chat アプリまたはカードから予期しない結果（カード メッセージが表示されないなど）が発生することがあります。

Chat の UI にエラー メッセージが表示されない場合もありますが、Chat アプリのエラーロギングがオンになっている場合は、エラー メッセージとログデータを使用してエラーを修正できます。エラーの表示、デバッグ、修正については、Google Chat のエラーのトラブルシューティングと修正をご覧ください。

関連トピック

• ButtonList
• Button
• Color
• knownIcon
• SelectionInput
• TextInput
• DateTimePicker ウィジェット