設計互動式資訊卡或對話方塊

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

您可以使用 Card Builder 設計及預覽即時通訊應用程式的 JSON 資訊卡訊息：

開啟卡片建構工具

先備知識

  • 可存取 Google Chat 的 Google Workspace 帳戶。
  • 已發布的 Chat 應用程式。如要建構 Chat 應用程式，請按照這個quickstart操作。

    • 新增按鈕

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

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

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

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

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

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

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

    以下內容顯示一張資訊卡，由包含兩個按鈕的 ButtonList 小工具組成。其中一個按鈕會使用 Color 欄位自訂按鈕的背景顏色。另一個按鈕已由 Disabled 欄位停用，這會導致使用者無法點選該按鈕並執行函式。

    新增有圖示的按鈕

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

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

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

    新增可選取的 UI 元素

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

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

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

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

    新增核取方塊

    以下顯示一個對話方塊，要求使用者透過使用核取方塊的 SelectionInput 小工具，指定聯絡人是專業或私人聯絡人，還是兩者並用：

    新增圓形按鈕

    下圖顯示一個對話方塊，要求使用者透過使用圓形按鈕的 SelectionInput 小工具，指定聯絡人是專業或個人：

    新增切換鈕

    以下顯示一個對話方塊，要求使用者透過使用切換按鈕的 SelectionInput 小工具，指定聯絡人是專業或私人人士，還是兩者並用：

    以下對話方塊會顯示對話方塊，要求使用者透過使用下拉式選單的 SelectionInput 小工具，指定聯絡人是專業或個人：

    新增複選選單

    下圖顯示了對話方塊，要求使用者從複選選單中選取聯絡人：

    針對複選選單使用資料來源

    本節說明如何使用複選選單填入動態來源 (例如 Google Workspace 應用程式或外部資料來源) 的資料。

    Google Workspace 的資料來源

    您可以透過 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
          }
        }
      }
    }
  }
}
    Google Workspace 以外的資料來源

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

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

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

    以下程式碼顯示了來自使用者外部一組聯絡人的複選選單。根據預設，選單會顯示一個聯絡人，並執行 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
    /**
 * 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
            },
          ]
        }
      }
    }
  };
}

    新增可讓使用者輸入文字的欄位

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

    如果需要收集使用者的抽像或不明資料，請使用這個 TextInput 小工具。如要向使用者收集定義的資料，請改用 SelectionInput 小工具。

    如要處理使用者輸入的文字，請參閱「接收表單資料」。

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

    讓使用者選擇日期和時間

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

    如要處理使用者輸入的日期和時間值，請參閱「接收表單資料」。

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

    驗證輸入至資訊卡的資料

    本頁面說明如何驗證已輸入至資訊卡 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 錯誤」。