在資訊卡中新增互動式 UI 元素

本頁說明如何在資訊卡中加入小工具和 UI 元素，讓使用者可以與 Google Chat 應用程式互動，例如按一下按鈕或提交資訊。

即時通訊應用程式可以使用下列 Chat 介面建構互動式資訊卡：

  • 含有一或多張資訊卡的訊息。
  • 首頁：這是在 Chat 應用程式即時訊息的「首頁」分頁中顯示的資訊卡。
  • 對話方塊是指透過訊息和首頁在新視窗中開啟的資訊卡。

當使用者與資訊卡互動時，即時通訊應用程式可以使用接收到的資料來處理並據以回應。詳情請參閱「收集及處理 Google Chat 使用者的資訊」。

使用 Card Builder 設計及預覽即時通訊應用程式的訊息和使用者介面：

開啟卡片建構工具

必要條件

已啟用互動功能的 Google Chat 應用程式。如要建立互動式 Chat 應用程式，請根據要使用的應用程式架構，完成下列其中一個快速入門：

新增按鈕

ButtonList 小工具會顯示一組按鈕。按鈕可以顯示文字和圖示，或同時顯示文字和圖示。每個 Button 都支援使用者點選按鈕時發生的 OnClick 動作。例如：

  • 使用 OpenLink 開啟超連結，為使用者提供更多資訊。
  • 執行執行自訂函式的 action，例如呼叫 API。

針對無障礙功能，按鈕支援替代文字。

新增可執行自訂函式的按鈕

以下資訊卡包含包含兩個按鈕的 ButtonList 小工具。點選一個按鈕，即可在新分頁中開啟 Google Chat 開發人員說明文件。另一個按鈕會執行名為 goToView() 的自訂函式，並傳遞 viewType="BIRD EYE VIEW" 參數。

新增採用質感設計樣式的按鈕

以下為採用不同質感設計按鈕樣式的一組按鈕。

如要套用 Material Design 樣式，請勿加入「color」屬性。

新增自訂顏色和已停用的按鈕

您可以設定 "disabled": "true"，禁止使用者按下按鈕。

以下內容顯示一張資訊卡，由包含兩個按鈕的 ButtonList 小工具組成。一個按鈕使用 Color 欄位自訂按鈕的背景顏色。另一個按鈕則會使用 Disabled 欄位停用，以免使用者按下按鈕並執行函式。

新增有圖示的按鈕

以下顯示包含 ButtonList 小工具和兩個圖示 Button 小工具的資訊卡。其中一個按鈕會使用 knownIcon 欄位顯示 Google Chat 的內建電子郵件圖示。另一個按鈕則使用 iconUrl 欄位來顯示自訂圖示小工具。

新增含有圖示和文字的按鈕

以下顯示的資訊卡包含 ButtonList 小工具，可提示使用者傳送電子郵件。第一個按鈕顯示電子郵件圖示，第二個按鈕則顯示文字。使用者可以點選圖示或文字按鈕來執行 sendEmail 函式。

自訂可收合區塊的按鈕

自訂控制按鈕，用於在資訊卡中收合和展開各個部分。您可以選擇一系列圖示或圖片，以視覺化方式呈現該區段的內容，讓使用者更容易理解資訊並進行互動。

新增溢位選單

您可以在 Chat 資訊卡中使用 Overflow menu 來提供其他選項和動作。這項功能可讓您加入更多選項，同時不讓資訊卡介面顯得雜亂，確保設計簡潔有條理。

新增 Chips 清單

ChipList 小工具能以多元且吸睛的方式顯示資訊。使用方塊清單來表示標記、類別或其他相關資料，方便使用者瀏覽內容並與內容互動。

向使用者收集資訊

本節說明如何新增可收集資訊的資訊方塊，例如文字或選項。

如要瞭解如何處理使用者輸入的內容，請參閱「收集並處理 Google Chat 使用者的資訊」一文。

收集文字

TextInput 小工具提供可讓使用者輸入文字的欄位。小工具支援建議功能，可協助使用者輸入統一資料，以及變更時的動作，也就是在文字輸入欄位發生變更時執行的 Actions，例如使用者新增或刪除文字。

如需從使用者收集抽象或未知的資料，請使用這個 TextInput 小工具。如要收集使用者定義的資料，請改用 SelectionInput 小工具。

以下是由 TextInput 小工具組成的資訊卡：

收集日期或時間

DateTimePicker 小工具可讓使用者輸入日期、時間，或同時輸入日期和時間。或者，使用者也可以使用挑選器選取日期和時間。如果使用者輸入無效的日期或時間，挑選器會顯示錯誤訊息，提示使用者正確輸入資訊。

以下顯示包含三種 DateTimePicker 小工具類型的資訊卡：

讓使用者選取項目

SelectionInput 小工具提供一組可選項目，例如核取方塊、圓形按鈕、切換鈕或下拉式選單。您可以使用這個小工具，向使用者收集已定義與標準化的資料。如要從使用者收集未定義的資料，請改用 TextInput 小工具。

SelectionInput 小工具支援建議功能，協助使用者輸入統一資料和變更期間動作，這些動作會在選項輸入欄位發生變更 (例如使用者選取或取消選取項目) 時執行。Actions

即時通訊應用程式可以接收及處理所選項目的值。如要進一步瞭解如何使用表單輸入，請參閱「處理使用者輸入的資訊」。

本節提供使用 SelectionInput 小工具的資訊卡範例。這些範例使用不同類型的區段輸入：

新增核取方塊

以下卡片會顯示使用者是否要指定聯絡人是工作聯絡人、私人聯絡人，或是兩者皆是，並使用 SelectionInput 小工具顯示核取方塊：

新增單選按鈕

以下項目顯示資訊卡，要求使用者透過使用圓形按鈕的 SelectionInput 小工具，指定聯絡人是專業或個人：

新增切換鈕

下圖顯示了一張資訊卡，要求使用者透過 SelectionInput 小工具使用切換按鈕，指定聯絡人是專業或私人人士，還是兩者並用：

下方資訊卡會顯示使用下拉式選單的 SelectionInput 小工具，要求使用者指定聯絡人是職業聯絡人還是私人聯絡人：

新增複選選單

以下內容顯示一張資訊卡，要求使用者從複選選單中選取聯絡人：

您可以透過 Google Workspace 的下列資料來源，為複選選單填入項目：

  • Google Workspace 使用者：您只能填入相同 Google Workspace 機構的使用者。
  • Chat 聊天室：使用者在複選選單中選取項目，只能查看及選取 Google Workspace 機構中的聊天室。

如要使用 Google Workspace 資料來源，請指定 platformDataSource 欄位。與其他選取輸入類型不同，您可以省略 SectionItem 物件，因為這些選取項目是從 Google Workspace 動態來源取得。

以下程式碼顯示 Google Workspace 使用者的複選選單。如要填入使用者，選項輸入來源會將 commonDataSource 設為 USER：

JSON

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

以下程式碼會顯示 Chat 空間的多重選取選單。如要填入空格，選項的輸入內容會指定 hostAppDataSource 欄位。複選選單也會將 defaultToCurrentSpace 設為 true，這會將目前空間設為選單中的預設選取項目：

JSON

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

複選選單也可以填入第三方或外部資料來源的項目。舉例來說，您可以使用複選選單，讓使用者從客戶關係管理 (CRM) 系統中的銷售待開發客戶清單中，選取項目。

如要使用外部資料來源，請使用 externalDataSource 欄位指定從資料來源傳回項目的函式。

如要減少對外部資料來源的要求，您可以在使用者於選單中輸入內容之前，先在複選選單中顯示建議項目。舉例來說，您可以填入最近搜尋的使用者聯絡人。如要從外部資料來源填入建議項目，請指定 SelectionItem 物件。

以下程式碼顯示了來自使用者外部一組聯絡人的複選選單。根據預設，選單會顯示一個聯絡人，並執行 getContacts 函式，從外部資料來源擷取及填入項目：

Node.js

node/selection-input/index.js
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

Python

python/selection-input/main.py
'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': "getContacts" },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_contact("3")]
}

Java

java/selection-input/src/main/java/com/google/chat/selectionInput/App.java
.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction("getContacts"))
  .setItems(List.of(getContact("3")))))))))));

Apps Script

apps-script/selection-input/selection-input.gs
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

針對外部資料來源，您也可以在多重選取選單中，自動完成使用者開始輸入的項目。舉例來說，如果使用者開始在選單中輸入 Atl，以便填入美國的城市，Chat 應用程式可以在使用者輸入完畢前，自動建議 Atlanta。最多可自動完成 100 個項目。

如要自動完成項目，請建立函式來查詢外部資料來源，並在使用者於複選選單中輸入內容時傳回項目。這個函式必須執行下列操作：

  • 傳遞代表使用者與選單互動的事件物件。
  • 找出互動事件的 invokedFunction 值與 externalDataSource 欄位的函式相符。
  • 函式相符時，系統會從外部資料來源傳回建議項目。如要根據使用者類型建議項目，請取得 autocomplete_widget_query 鍵的值。這個值代表使用者在選單中輸入的內容。

以下程式碼會自動完成外部資料資源中的項目。在上例中，Chat 應用程式會根據觸發 getContacts 函式的時間來建議項目：

Node.js

node/selection-input/index.js
/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
      // Only return items based on the query from the user
      ].filter(e => !query || e.text.includes(query))}}
    }};
  }
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Python

python/selection-input/main.py
def on_widget_update(event: dict) -> dict:
  """Responds to a WIDGET_UPDATE event in Google Chat."""
  if "getContacts" == event.get("common").get("invokedFunction"):
    query = event.get("common").get("parameters").get("autocomplete_widget_query")
    return { 'actionResponse': {
      'type': "UPDATE_WIDGET",
      'updatedWidget': { 'suggestions': { 'items': list(filter(lambda e: query is None or query in e["text"], [
        # The list is static here but it could be dynamic.
        get_contact("1"), get_contact("2"), get_contact("3"), get_contact("4"), get_contact("5")
      # Only return items based on the query from the user
      ]))}}
    }}


def get_contact(id: str) -> dict:
  """Generate a suggested contact given an ID."""
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

Java

java/selection-input/src/main/java/com/google/chat/selectionInput/App.java
// Responds to a WIDGET_UPDATE event in Google Chat.
Message onWidgetUpdate(JsonNode event) {
  if ("getContacts".equals(event.at("/invokedFunction").asText())) {
    String query = event.at("/common/parameters/autocomplete_widget_query").asText();
    return new Message().setActionResponse(new ActionResponse()
      .setType("UPDATE_WIDGET")
      .setUpdatedWidget(new UpdatedWidget()
        .setSuggestions(new SelectionItems().setItems(List.of(
          // The list is static here but it could be dynamic.
          getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
        // Only return items based on the query from the user
        ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList()))));
  }
  return null;
}

// Generate a suggested contact given an ID.
GoogleAppsCardV1SelectionItem getContact(String id) {
  return new GoogleAppsCardV1SelectionItem()
    .setValue(id)
    .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
    .setText("Contact " + id);
}

Apps Script

apps-script/selection-input/selection-input.gs
/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
      // Only return items based on the query from the user
      ].filter(e => !query || e.text.includes(query))}}
    }};
  }
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

驗證輸入至資訊卡的資料

本頁面說明如何驗證已輸入至資訊卡 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 應用程式或資訊卡傳回錯誤時，Chat 介面會顯示「發生錯誤」的訊息。或「無法處理你的要求」。Chat UI 有時不會顯示任何錯誤訊息，但 Chat 應用程式或資訊卡卻產生非預期的結果，例如資訊卡可能不會顯示。

雖然 Chat UI 可能不會顯示錯誤訊息，但可以在啟用 Chat 擴充應用程式的錯誤記錄功能時，查看描述性的錯誤訊息和記錄資料，協助您修正錯誤。如需查看、偵錯及修正錯誤的相關說明，請參閱「排解及修正 Google Chat 錯誤」一文。