本頁面由 Cloud Translation API 翻譯而成。

在資訊卡中新增互動式 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 按鈕中顯示一組按鈕。。

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

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

您可以透過設定 "disabled": "true" 來避免使用者點選按鈕。

以下內容顯示包含兩個 ButtonList 小工具的資訊卡按鈕。點選其中一個按鈕會用到 Color 欄位自訂按鈕背景顏色。另一個按鈕也會透過 Disabled 欄位停用，防止使用者點選按鈕並執行函式。

新增有圖示的按鈕

以下內容顯示了由包含兩個圖示的 ButtonList 小工具組成的資訊卡 Button 個小工具。點選其中一個按鈕會用到 knownIcon敬上 ] 欄位顯示 Google Chat 的內建電子郵件圖示。另一個按鈕會使用 iconUrl 欄位，即可顯示「自訂圖示小工具」。

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

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

自訂可收合區塊的按鈕

自訂控制項按鈕，用於收合及展開資訊卡從各種圖示或圖片中選擇部分的內容，方便使用者理解這些資訊

新增溢位選單

Overflow menu敬上，以提供更多選項和動作。有了提供了更多選項，而且不會影響資訊卡的介面，確保簡潔有條的設計

新增方塊清單

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敬上如需儲存大量結構化物件建議使用 Cloud Bigtable

下方程式碼顯示使用者的外部聯絡人群組根據預設，選單會顯示一位聯絡人然後執行 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敬上值與 externalDataSource 欄位的函式相符。
函式相符時，從外部資料傳回建議項目來源。如要根據使用者輸入的內容建議項目，請取得 autocomplete_widget_query 金鑰。這個值代表使用者輸入的內容。

以下程式碼會自動完成外部資料資源中的項目。使用 Chat 應用程式會根據觸發 getContacts 函式時：

Apps Script

apps-script/selection-input/on-widget-update.gs

前往 GitHub 查看

/**
 * 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

前往 GitHub 查看

/**
 * 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 UI 不會顯示任何錯誤訊息，但 Chat 應用程式或資訊卡產生非預期的結果例如資訊卡訊息顯示。

雖然 Chat UI 中可能不會顯示錯誤訊息，提供描述性錯誤訊息和記錄資料，協助您修正錯誤。如需觀看說明，偵錯及修正錯誤，請參閱疑難排解並修正 Google Chat 錯誤。

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

必要條件

新增按鈕

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

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

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

新增有圖示的按鈕

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

自訂可收合區塊的按鈕

新增溢位選單

新增方塊清單

向使用者收集資訊

收集文字

收集日期或時間

允許使用者選取項目

新增核取方塊

新增圓形按鈕

新增切換鈕

新增下拉式選單

新增複選選單

JSON

JSON

JSON

Apps Script

Node.js

驗證輸入至資訊卡的資料

設定動作所需的小工具

在複選功能中設定all_widgets_are_required動作

JSON

在 dateTimePicker 中設定 all_widgets_are_required 動作

JSON

在下拉式選單中設定all_widgets_are_required動作

JSON

設定文字輸入小工具的驗證設定

設定文字輸入小工具的字元限制

JSON

設定文字輸入小工具的輸入類型

JSON

疑難排解

相關主題

在複選功能中設定`all_widgets_are_required`動作

在 dateTimePicker 中設定 `all_widgets_are_required` 動作

在下拉式選單中設定`all_widgets_are_required`動作