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

本頁說明如何在資訊卡中新增小工具和 UI 元素，讓使用者與 Google Chat 應用程式互動，例如點選按鈕或提交資訊。

Chat 擴充應用程式可使用下列 Chat 介面建構互動式資訊卡：

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

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

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

開啟資訊卡製作工具

必要條件

Google Chat 應用程式，已設定為接收及回應使用者互動。如要建立互動式 Chat 應用程式，請根據您要使用的應用程式架構，完成下列其中一項快速入門導覽課程：

新增按鈕

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

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

為方便無障礙工具使用，按鈕支援替代文字。

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

以下資訊卡包含一個 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 資訊卡，提供其他選項和動作。這樣一來，您就能加入更多選項，同時確保資訊卡介面簡潔有序。

新增方塊清單

ChipList 小工具提供多功能且美觀的資訊顯示方式。使用方塊清單代表標記、類別或其他相關資料，讓使用者更輕鬆地瀏覽內容及與內容互動。

收集使用者資訊

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

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

收集文字

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

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

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

收集日期或時間

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

以下顯示由三種不同類型 DateTimePicker 小工具組成的資訊卡：

讓使用者選取項目

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

SelectionInput 小工具支援建議功能，可協助使用者輸入統一格式的資料，並支援變更時動作，也就是當選取輸入欄位發生變更時 (例如使用者選取或取消選取項目)，執行的 Actions。

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

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

新增核取方塊

以下資訊卡會要求使用者指定聯絡人是專業、個人或兩者，並使用核取方塊的 SelectionInput 小工具：

新增圓形按鈕

以下顯示的資訊卡會要求使用者指定聯絡人是專業人士或個人，並使用 SelectionInput 小工具提供圓形按鈕：

新增切換鈕

以下資訊卡會要求使用者指定聯絡人是專業、個人或兩者皆是，並使用 SelectionInput 小工具切換：

以下資訊卡會要求使用者指定聯絡人是專業人士或個人，並使用下拉式選單的 SelectionInput 小工具：

動態填入下拉式選單

適用於 Google Chat 應用程式。

您可以從 Google Workspace 或外部資料來源，動態填入下拉式選單的項目。如要使用動態資料來源，請指定 dataSourceConfigs 欄位，這是 DataSourceConfig 物件的陣列。每個 DataSourceConfig 可包含 platformDataSource 或 remoteDataSource。目前僅支援一個 DataSourceConfig。

填入 Google Workspace 中的項目

如要從 Google Workspace 資料來源 (例如 Google Workspace 使用者) 填入項目，請在 DataSourceConfig 中指定 platformDataSource 欄位。與使用靜態 items 不同，您會省略 SelectionItem 物件，因為這些選取項目是從 Google Workspace 動態取得。

下列程式碼會顯示下拉式選單，其中填入 Google Workspace 使用者：

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "contacts",
            "type": "DROPDOWN",
            "label": "Select contact from organization",
            "dataSourceConfigs": [
              {
                "platformDataSource": {
                  "commonDataSource": "USER"
                },
                "minCharactersTrigger": 1
              }
            ]
          }
        }
      ]
    }
  ]
}
從外部資料來源填入項目

如要從第三方或外部資料來源 (例如客戶關係管理 (CRM) 系統) 填入項目，請使用 DataSourceConfig 中的 remoteDataSource 欄位，指定從資料來源傳回項目的函式。

下列程式碼顯示下拉式選單，可透過執行 getCrmLeads 函式，填入外部聯絡人組合中的項目：

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "crm_leads",
            "type": "DROPDOWN",
            "label": "Select CRM Lead",
            "dataSourceConfigs": [
              {
                "remoteDataSource": {
                  "function": "getCrmLeads"
                },
                "minCharactersTrigger": 2
              }
            ],
            "items": [
              {
                "text": "Suggested Lead 1",
                "value": "lead-1"
              }
            ]
          }
        }
      ]
    }
  ]
}

如要減少對動態資料來源的要求，您可以在使用者輸入內容前，在下拉式選單中顯示建議項目。您也可以在 DataSourceConfig 中設定 minCharactersTrigger，根據使用者輸入的內容，設定下拉式選單自動完成項目。當使用者輸入的字元數達到 minCharactersTrigger 中指定的數量時，系統就會觸發 remoteDataSource 中指定的函式。傳遞至函式的事件物件包含 autocomplete_widget_query 鍵中的使用者輸入內容。

新增多重選取選單

以下資訊卡會要求使用者從複選選單中選取聯絡人：

您可以從 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 物件。

下列程式碼範例顯示多選選單，可從外部資料來源查詢及填入項目：

Node.js

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

將 FUNCTION_URL 替換為查詢外部資料來源的 HTTP 端點。

Python

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

將 FUNCTION_URL 替換為查詢外部資料來源的 HTTP 端點。

Java

java/chat/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(FUNCTION_URL))
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  .setItems(List.of(getSuggestedContact("3")))))))))));

將 FUNCTION_URL 替換為查詢外部資料來源的 HTTP 端點。

Apps Script

這個範例會傳回資訊卡 JSON，藉此傳送資訊卡訊息。您也可以使用 Apps Script 卡片服務。

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

從動態資料來源填入建議項目

如果是外部資料來源，您也可以在多選選單或下拉式選單中，自動完成及建議使用者開始輸入的項目。舉例來說，如果使用者開始輸入 Atl，Chat 擴充應用程式可以在使用者完成輸入前，自動建議 Atlanta。最多可建議 100 個項目。

如要傳回建議項目，查詢外部資料來源的函式必須執行下列操作：

  1. 處理事件物件：使用者在選單中輸入內容時，Chat 應用程式會收到這個物件。
  2. 從事件物件中，取得使用者輸入的值，該值會顯示在 event.commonEventObject.parameters["autocomplete_widget_query"] 欄位中。
  3. 使用使用者輸入的值查詢資料來源，取得一或多個 SelectionItems 建議給使用者。
  4. 傳回 RenderActions 動作和 modifyCard 物件，即可傳回建議項目。

下列程式碼範例說明 Chat 應用程式如何動態建議資訊卡多選選單中的項目。當使用者在選單中輸入內容時，小工具 externalDataSource 欄位中提供的函式或端點會查詢外部資料來源，並建議使用者可選取的項目：

Node.js

node/chat/selection-input/index.js
/**
 * Web app that responds to events sent from a Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
app.post('/', async (req, res) => {
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.json(queryContacts(req.body));
  }

  // Replies with a card that contains the multiselect menu.
  return res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: FUNCTION_URL },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
});

/**
 * Get contact suggestions based on text typed by users.
 *
 * @param {Object} event the event object that contains the user's query
 * @return {Object} suggestions
 */
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("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 selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

將 FUNCTION_URL 替換為查詢外部資料來源的 HTTP 端點。

Python

python/chat/selection-input/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: The response
  """
  # Stores the Google Chat event
  chatEvent = request.get_json().get('chat')

  # Handle user interaction with multiselect.
  if chatEvent.get('widgetUpdatedPayload') is not None:
    return json.jsonify(query_contacts(request.get_json()))

  # Replies with a card that contains the multiselect menu.
  return json.jsonify({ 'hostAppDataAction': { 'chatDataAction': { 'createMessageAction': {
    'message': { 'cardsV2': [{
      'cardId': "contactSelector",
      'card': { 'sections':[{ 'widgets': [{
        'selectionInput': {
          'name': "contacts",
          'type': "MULTI_SELECT",
          'label': "Selected contacts",
          'multiSelectMaxSelectedItems': 3,
          'multiSelectMinQueryLength': 1,
          'externalDataSource': { 'function': FUNCTION_URL },
          # Suggested items loaded by default.
          # The list is static here but it could be dynamic.
          'items': [get_suggested_contact("3")]
        }
      }]}]}
    }]}
  }}}})


def query_contacts(event: dict) -> dict:
  """Get contact suggestions based on text typed by users.

  Args:
      event (Mapping[str, Any]): The event object that contains the user's query

  Returns:
      Mapping[str, Any]: The response with contact suggestions.
  """
  query = event.get("commonEventObject").get("parameters").get("autocomplete_widget_query")
  return { 'action': { 'modifyOperations': [{ 'updateWidget': { 'selectionInputWidgetSuggestions': { 'suggestions': list(
    filter(lambda e: query is None or query in e["text"], [
      # The list is static here but it could be dynamic.
      get_suggested_contact("1"), get_suggested_contact("2"), get_suggested_contact("3"), get_suggested_contact("4"), get_suggested_contact("5")
    # Only return items based on the query from the user
    ])
  )}}}]}}


def get_suggested_contact(id: str) -> dict:
  """Generate a suggested contact given an ID.

  Args:
      id (str): The ID of the contact to return.

  Returns:
      Mapping[str, Any]: The contact formatted as a selection item in the menu.
  """
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

將 FUNCTION_URL 替換為查詢外部資料來源的 HTTP 端點。

Java

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java
@SpringBootApplication
@RestController
// Web app that responds to events sent from a Google Chat space.
public class App {
  private static final String FUNCTION_URL = "your-function-url";

  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /**
   * Handle requests from Google Chat
   * 
   * @param event the event object sent by Google Chat
   * @return The response to be sent back to Google Chat
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    // Stores the Google Chat event
    JsonNode chatEvent = event.at("/chat");

    // Handle user interaction with multiselect.
    if (!chatEvent.at("/widgetUpdatedPayload").isEmpty()) {
      return queryContacts(event);
    }

    // Replies with a card that contains the multiselect menu.
    Message message = new Message().setCardsV2(List.of(new CardWithId()
      .setCardId("contactSelector")
      .setCard(new GoogleAppsCardV1Card()
        .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(new GoogleAppsCardV1Widget()
          .setSelectionInput(new GoogleAppsCardV1SelectionInput()
            .setName("contacts")
            .setType("MULTI_SELECT")
            .setLabel("Selected contacts")
            .setMultiSelectMaxSelectedItems(3)
            .setMultiSelectMinQueryLength(1)
            .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
            // Suggested items loaded by default.
            // The list is static here but it could be dynamic.
            .setItems(List.of(getSuggestedContact("3")))))))))));

    return new GenericJson() {{
      put("hostAppDataAction", new GenericJson() {{
        put("chatDataAction", new GenericJson() {{
          put("createMessageAction", new GenericJson() {{
            put("message", message);
          }});
        }});
      }});
    }};
  }

  /**
   * Get contact suggestions based on text typed by users.
   *
   * @param event the event object that contains the user's query.
   * @return The response with contact suggestions.
   */
  GenericJson queryContacts(JsonNode event) throws Exception {
    String query = event.at("/commonEventObject/parameters/autocomplete_widget_query").asText();
    List<GoogleAppsCardV1SelectionItem> suggestions = List.of(
      // The list is static here but it could be dynamic.
      getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
    // Only return items based on the query from the user
    ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList();

    return new GenericJson() {{
      put("action", new GenericJson() {{
        put("modifyOperations", List.of(new GenericJson() {{
          put("updateWidget", new GenericJson() {{
            put("selectionInputWidgetSuggestions", new GenericJson() {{
              put("suggestions", suggestions);
            }});
          }});
        }}));
      }});
    }};
  }

  /**
   * Generate a suggested contact given an ID.
   * 
   * @param id The ID of the contact to return.
   * @return The contact formatted as a selection item in the menu.
   */
  GoogleAppsCardV1SelectionItem getSuggestedContact(String id) {
    return new GoogleAppsCardV1SelectionItem()
      .setValue(id)
      .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
      .setText("Contact " + id);
  }
}

將 FUNCTION_URL 替換為查詢外部資料來源的 HTTP 端點。

Apps Script

這個範例會傳回資訊卡 JSON，藉此傳送資訊卡訊息。您也可以使用 Apps Script 卡片服務。

apps-script/chat/selection-input/selection-input.gs
/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("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 selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

驗證輸入資訊卡的資料

本頁說明如何驗證輸入至資訊卡 action 和小工具的資料。舉例來說，您可以驗證文字輸入欄位是否含有使用者輸入的文字，或是否包含特定數量的字元。

設定動作的必要小工具

在資訊卡的 action 中，將動作所需的小工具名稱新增至 requiredWidgets 清單。

如果叫用這個動作時，此處列出的任何小工具都沒有值，系統就會取消提交表單動作。

為動作設定 "allWidgetsAreRequired": true 時，這項動作會要求卡片中的所有小工具。

在多重選取中設定allWidgetsAreRequired動作

JSON

{
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "allWidgetsAreRequired": 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 中設定 allWidgetsAreRequired 動作

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":{
              "allWidgetsAreRequired": 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"
          }
        }
      ]
    }
  ]
}
在下拉式選單中設定allWidgetsAreRequired動作

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "allWidgetsAreRequired": 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": {"characterLimit": 15},
            "onChangeAction":{
              "allWidgetsAreRequired": 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": {
              "inputType": "EMAIL"
            },
            "onChangeAction": {
              "allWidgetsAreRequired": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "inputType": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "inputType": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

疑難排解

當 Google Chat 應用程式或資訊卡傳回錯誤時，Chat 介面會顯示「發生錯誤」訊息。或「無法處理你的要求。」有時 Chat UI 不會顯示任何錯誤訊息，但 Chat 擴充應用程式或資訊卡會產生非預期的結果，例如可能不會顯示資訊卡訊息。

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

非外掛程式的 Chat 擴充應用程式：設計互動式資訊卡和對話方塊

下列說明文件適用於非 Google Workspace 外掛程式的 Chat 應用程式。如要遷移非外掛程式的 Chat 擴充應用程式，請參閱「將 Google Chat 擴充應用程式轉換為 Google Workspace 外掛程式」。

下列程式碼顯示 Chat 應用程式 (非外掛程式) 中，使用者外部聯絡人項目的多選選單。根據預設，選單會顯示一位聯絡人，並執行 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")]
}

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

  • 傳遞代表使用者與選單互動的事件物件。
  • 確認互動事件的 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
  };
}