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

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

Chat 應用程式可以使用下列 Chat 介面建立互動式資訊卡：

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

當使用者與資訊卡互動時，Chat 應用程式可以使用收到的資料進行處理，並做出相應回應。詳情請參閱「收集並處理 Google Chat 使用者的資訊」。

使用資訊卡建構工具，設計及預覽 Chat 應用程式的訊息和使用者介面：

開啟資訊卡建立工具

必要條件

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

新增按鈕

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

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

按鈕支援替代文字，以便無障礙使用。

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

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

新增 Material Design 風格的按鈕

以下顯示一組採用不同 Material Design 按鈕樣式的按鈕。

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

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

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

以下顯示的卡片包含一個 ButtonList 小工具，其中有兩個按鈕。一個按鈕使用 Color 欄位自訂按鈕的背景顏色。另一個按鈕則會使用 Disabled 欄位停用，以免使用者按下按鈕並執行函式。

新增含有圖示的按鈕

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

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

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

自訂可摺疊區段的按鈕

自訂用於收合資訊卡內部各個部分的控制按鈕。從多種圖示或圖片中選擇，以視覺化方式呈現該部分的內容，方便使用者瞭解並與資訊互動。

新增溢位選單

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

新增 Chips 清單

ChipList 小工具提供多用途且視覺效果出色的資訊顯示方式。使用方塊清單來代表標記、類別或其他相關資料，讓使用者更容易瀏覽及與您的內容互動。

向使用者收集資訊

本節說明如何新增可收集資訊 (例如文字或選項) 的小工具。

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

收集文字

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

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

以下是包含 TextInput 小工具的資訊卡：

收集日期或時間

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

以下顯示一張卡片，其中包含三種不同類型的 DateTimePicker 小工具：

讓使用者選取項目

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

SelectionInput 小工具支援建議，可協助使用者輸入一致的資料，以及變更時的動作，也就是在選取輸入欄位發生變更時執行的 Actions，例如使用者選取或取消選取項目。

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

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

新增核取方塊

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

新增單選按鈕

下方資訊卡會使用使用無線電按鈕的 SelectionInput 小工具，要求使用者指定聯絡人是職業還是私人：

新增切換鈕

下方資訊卡會要求使用者透過使用開關的 SelectionInput 小工具，指定聯絡人是工作、私人聯絡人，還是兩者皆是：

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

新增多重選取選單

下方顯示的資訊卡會要求使用者從多重選取選單中選取聯絡人：

您可以使用 Google Workspace 中的下列資料來源，為多重選取選單填入項目：

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

如要使用 Google Workspace 資料來源，請指定 platformDataSource 欄位。與其他選項輸入類型不同，您可以省略 SelectionItem 物件，因為這些選項項目會動態取自 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 錯誤」一文。