インタラクティブな UI 要素をカードに追加する

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

Chat アプリでは次の Chat インターフェースを使用できます インタラクティブなカードを作成するには:

  • メッセージ 1 枚以上のカードを含む画像が表示されます
  • ホームページ これは、[ホーム] タブから直接表示されるカードで、 やり取りできます。
  • ダイアログ: 開くカードです。 新しいウィンドウで メッセージとホームページを表示します

ユーザーがカードを操作すると、Chat アプリは それに応じて処理と対応を行います詳しくは、 Google Chat ユーザーから情報を収集して処理する


カードビルダーを使用して、Chat 用アプリのメッセージとユーザー インターフェースを設計し、プレビューします。

カードビルダーを開く

前提条件

インタラクティブ機能を有効にする Google Chat アプリ。新しい 次のいずれかのクイックスタートを完了してください。 使用するアプリ アーキテクチャ:

ボタンを追加する

ButtonList ウィジェット 一連のボタンを表示します。ボタンには、テキスト、画像、音声、 またはテキストとアイコンの両方を指定できます。各 Button サポート OnClick 件のアクション ユーザーがボタンをクリックしたときに発生するイベントです。例:

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

ユーザー補助機能については、ボタンで代替テキストがサポートされています。

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

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

マテリアル デザイン スタイルのボタンを追加する

以下は、さまざまなマテリアル デザインのボタンを示しています。 。

マテリアル デザインのスタイルを適用するには、color [色] オプションを属性です。

カスタム色のボタンと無効なボタンを追加する

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

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

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

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

アイコンとテキスト付きのボタンを追加する

以下は、プロンプトを表示する ButtonList ウィジェットで構成されるカードの例です。 ユーザーにメールを送信します。最初のボタンはメールのアイコンと 2 つ目のボタンはテキストを表示します。ユーザーはアイコンかテキスト sendEmail 関数を実行するボタン。

折りたたみ可能なセクションのボタンをカスタマイズする

コントロール ボタンをカスタマイズして、 。さまざまなアイコンや画像から選択して ユーザーが簡単に内容を理解して操作できるようにし、 提供します。

オーバーフロー メニューの追加

Overflow menu を使用すると、追加のオプションやアクションを提供できます。これにより、 カードのインターフェースをすっきりさせることなく、より多くのオプションを 整理整頓されたデザインです。

チップのリストを追加する

ChipList 多様で視覚的に魅力のある情報を表示できます。 チップリストを使ってタグやカテゴリなどの関連データを表現し、 コンテンツを容易に操作できるようになります

ユーザーから情報を収集する

このセクションでは、 選択することもできます。

ユーザーが入力した内容を処理する方法については、以下をご覧ください。 Google Chat ユーザーから情報を収集して処理する

テキストを収集する

TextInput ウィジェット には、ユーザーがテキストを入力できるフィールドがあります。「 ウィジェットは、ユーザーが均一なデータを入力するのに役立つ提案をサポートし、 アクション Actions テキスト入力フィールドに変更が発生したときに実行されます。 表示されます。

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

以下は、TextInput ウィジェットで構成されるカードです。

日時を収集する

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

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

ユーザーがアイテムを選択できるようにする

SelectionInput ウィジェット チェックボックス、ラジオボタン、スイッチ、 またはプルダウンメニューから選択できますこのウィジェットを使用できます 定義および標準化されたデータをユーザーから収集します。未定義のデータを収集するため 代わりに TextInput ウィジェットを使用してください。

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

Chat アプリは、選択されたアイテムの値を受け取って処理できます。 フォーム入力の操作について詳しくは、以下をご覧ください。 ユーザーが入力した情報を処理する

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

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

以下では、ユーザーがファイルを開くかどうかを指定するカードを表示します。 仕事用、個人用、またはその両方の連絡先に、SelectionInput ウィジェットで チェックボックスを使用しています。

ラジオボタンを追加する

以下では、ユーザーがファイルを開くかどうかを指定するカードを表示します。 仕事でもプライベートでも、SelectionInput ウィジェットで ラジオボタン:

スイッチを追加する

以下では、ユーザーがファイルを開くかどうかを指定するカードを表示します。 ビジネス用、個人用、またはその両方に使用する SelectionInput ウィジェットを使用する スイッチを使用する:

以下では、ユーザーがファイルを開くかどうかを指定するカードを表示します。 仕事でもプライベートでも、SelectionInput ウィジェットで プルダウン メニュー:

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

以下では、ユーザーに連絡先の選択を求めるカードを表示します。 複数選択メニューから作成するには:

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

  • Google Workspace ユーザー: ユーザーを入力できるのは、 同じ Google Workspace 組織に割り当てられています。
  • Chat スペース: ユーザーが複数選択でアイテムを入力している メニューでは、スペース内でそのユーザーが所属するスペースのみを表示、選択できます。 Google Workspace の組織。

Google Workspace のデータソースを使用するには、 platformDataSource 表示されます。他の選択入力タイプとは異なり SectionItem 選択されることがあります。これらの選択項目は、 Google Workspace です

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

JSON

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

次のコードは、Chat の複数選択メニューを示しています。 できます。スペースを入力するには、選択入力で hostAppDataSource フィールド。複数選択メニューでは defaultToCurrentSpacetrue に変更し、現在のスペースをデフォルトにします :

JSON

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

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

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

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

次のコードは、 外部連絡先のセットですデフォルトでは、メニューに 1 件の連絡先が表示されます getContacts 関数を実行して、 外部データソース:

JSON

{
  "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 value は、externalDataSource フィールドの関数と一致します。
  • 関数が一致すると、外部データから候補アイテムを返す あります。ユーザーの入力内容に基づいてアイテムを提案するには、 autocomplete_widget_query キーこの値はユーザーが入力した を選択します。

次のコードでは、外部データリソースのアイテムが予測入力されます。 前述の例では、Chat 用アプリは 関数 getContacts がトリガーされたとき:

Apps Script

apps-script/selection-input/on-widget-update.gs
/**
 * 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
            },
          ]
        }
      }
    }
  };
}

Node.js

node/selection-input/on-widget-update.js
/**
 * 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
            },
          ]
        }
      }
    }
  };
}

カードに入力されたデータを検証する

このページでは、カードの action に入力されたデータを検証する方法について説明します。 サポートしています。 たとえば、テキスト入力フィールドに 文字数が特定の文字列が含まれることを検出できます。

アクションに必要なウィジェットを設定する

カードの action の一部として、 アクションで必要なウィジェットの名前を requiredWidgets リストに追加する。

ここにリストされているウィジェットの中に、このアクションが呼び出されたときに値がないものがあれば、 フォーム アクションの送信はキャンセルされます。

アクションに対して "all_widgets_are_required": "true" が設定されている場合、すべてのウィジェット 必要なアクションが表示されます。

複数選択での all_widgets_are_required アクションの設定

JSON

{
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "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
              }
            ]
          }
        }
      ]
    }
  ]
}
dateTimePicker で all_widgets_are_required アクションを設定する

JSON

{
  "sections": [
    {
      "widgets": [
        {
          "textParagraph": {
            "text": "A datetime picker widget with both date and time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_and_time",
            "label": "meeting",
            "type": "DATE_AND_TIME"
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just date:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_only",
            "label": "Choose a date",
            "type": "DATE_ONLY",
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_time_only",
            "label": "Select a time",
            "type": "TIME_ONLY"
          }
        }
      ]
    }
  ]
}
プルダウン メニューで all_widgets_are_required アクションを設定する

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "items": [
              {
                "text": "Red",
                "value": "red",
                "selected": false
              },
              {
                "text": "Green",
                "value": "green",
                "selected": false
              },
              {
                "text": "White",
                "value": "white",
                "selected": false
              },
              {
                "text": "Blue",
                "value": "blue",
                "selected": false
              },
              {
                "text": "Black",
                "value": "black",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}

テキスト入力ウィジェットの検証を設定する

textInput ウィジェットの検証フィールドを使用して、ウィジェットの文字数制限と入力タイプを 作成します。

テキスト入力ウィジェットの文字数制限を設定する

JSON

{
  "sections": [
    {
      "header": "Tell us about yourself",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "favoriteColor",
            "label": "Favorite color",
            "type": "SINGLE_LINE",
            "validation": {"character_limit":15},
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        }
      ]
    }
  ]
}
テキスト入力ウィジェットの入力タイプを設定する

JSON

{
  "sections": [
    {
      "header": "Validate text inputs by input types",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "mailing_address",
            "label": "Please enter a valid email address",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "EMAIL"
            },
            "onChangeAction": {
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "input_type": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

トラブルシューティング

Google Chat アプリまたは card がエラーを返した場合、 Chat のインターフェースに「エラーが発生しました」というメッセージが表示されている。 または「リクエストを処理できません」が表示されます。場合によっては、Chat の UI が エラー メッセージは表示されませんが、Chat 用アプリまたは 予期しない結果が生じた場合たとえば、カード メッセージに 表示されます。

Chat UI にエラー メッセージが表示されない場合がありますが、 エラーの修正に役立つ、わかりやすいエラー メッセージとログデータ Chat 用アプリのエラーロギングが有効になっている場合。表示のヘルプについては、 エラーの修正について詳しくは、このモジュールの Google Chat のエラーのトラブルシューティングと修正