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

建構互動式對話方塊

本頁面說明 Google Chat 應用程式如何開啟對話方塊，顯示使用者介面 (UI) 並回應使用者。

對話方塊是基於資訊卡的視窗介面，可從 Chat 聊天室或訊息開啟。對話方塊及其內容只會顯示給開啟對話方塊的使用者。

Chat 擴充應用程式可以使用對話方塊，向 Chat 使用者要求及收集資訊，包括多步驟表單。如要進一步瞭解如何建構表單輸入內容，請參閱「收集及處理使用者資訊」。

必要條件

HTTP

可擴充 Google Chat 功能的 Google Workspace 外掛程式。如要建構一個，請完成 HTTP 快速入門導覽。

Apps Script

可擴充 Google Chat 功能的 Google Workspace 外掛程式。如要建構巨集，請完成 Apps Script 快速入門。

開啟對話方塊

對話方塊，內含各種不同的小工具。 — **圖 1**：Chat 應用程式會開啟對話方塊，收集聯絡資訊。

本節說明如何透過下列方式回應及設定對話：

透過使用者互動觸發對話方塊要求。
傳回並開啟對話方塊，處理要求。
使用者提交資訊後，請關閉對話方塊或傳回另一個對話方塊，以處理提交內容。

觸發對話方塊要求

Chat 應用程式只能在回應使用者互動時開啟對話方塊，例如指令或資訊卡中訊息的按鈕點選動作。

如要透過對話方塊回覆使用者，Chat 應用程式必須建構會觸發對話方塊要求的互動，例如：

回應指令。如要透過指令觸發要求，請在設定指令時勾選「開啟對話方塊」核取方塊。
回應按鈕點擊動作：在訊息中，無論是資訊卡的一部分或位於訊息底部，如要從訊息中的按鈕觸發要求，請將按鈕的 onClick 動作設定為 interaction，並將其 OPEN_DIALOG 設為 OPEN_DIALOG。

觸發對話方塊的按鈕 — **圖 2**：即時通訊應用程式傳送訊息，提示使用者使用 `/addContact` 斜線指令。
訊息中也會包含按鈕，使用者點選即可觸發指令。

下列 JSON 顯示如何從訊息中的按鈕觸發對話方塊要求。如要開啟對話方塊，請將按鈕的欄位設為 OPEN_DIALOG： onClick.action.interaction

{
  "buttonList": { "buttons": [{
    "text": "BUTTON_TEXT",
    "onClick": { "action": {
      "function": "ACTION_FUNCTION",
      "interaction": "OPEN_DIALOG"
    }}
  }]}
}

其中 BUTTON_TEXT 是按鈕中顯示的文字，ACTION_FUNCTION 則是執行以開啟初始對話方塊的函式。

開啟初始對話方塊

使用者觸發對話方塊要求時，Chat 應用程式會收到事件物件，其中包含指定 dialogEventType 物件為 REQUEST_DIALOG 的酬載。

如要開啟對話方塊，Chat 應用程式可以傳回含有導覽 pushCard 的 RenderActions 物件，藉此回應要求，顯示對話方塊。資訊卡應包含任何使用者介面 (UI) 元素，包括一或多個 sections[] 小工具。如要向使用者收集資訊，可以指定表單輸入小工具和按鈕小工具。如要進一步瞭解如何設計表單輸入內容，請參閱「收集及處理使用者資訊」。

下列 JSON 顯示 Chat 應用程式如何傳回開啟對話方塊的回應：

{
  "action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
    WIDGETS,
    { "buttonList": { "buttons": [{
      "text": "BUTTON_TEXT",
      "onClick": {
        "action": { "function": "ACTION_FUNCTION" }
      }
    }]}}
  }]}]}}]}
}

其中 BUTTON_TEXT 是按鈕中顯示的文字 (例如 Next 或 Submit)，WIDGETS 代表一或多個表單輸入小工具，而 ACTION_FUNCTION 是動作的回呼函式，會在使用者點選按鈕時執行。

處理對話方塊提交作業

使用者點選提交對話方塊的按鈕時，您的 Chat 應用程式會收到含有 ButtonClickedPayload 物件的事件物件。在酬載中，dialogEventType 會設為 SUBMIT_DIALOG。如要瞭解如何收集及處理對話方塊中的資訊，請參閱「收集及處理 Google Chat 使用者的資訊」。

您的 Chat 應用程式必須回應事件物件，方法如下：

傳回另一個對話方塊，填入另一張卡片或表單。
驗證使用者提交的資料後，關閉對話方塊，並視需要傳送確認訊息。

選用：傳回其他對話方塊

使用者提交初始對話方塊後，Chat 應用程式可以傳回一或多個額外對話方塊，協助使用者在提交前檢查資訊、填寫多步驟表單，或動態填入表單內容。

如要處理使用者輸入的資料，Chat 應用程式會在事件的 commonEventObject.formInputs 物件中處理資料。如要進一步瞭解如何從輸入小工具擷取值，請參閱「收集及處理使用者資訊」。

如要追蹤使用者在初始對話方塊中輸入的任何資料，您必須在開啟下一個對話方塊的按鈕中新增參數。詳情請參閱「將資料轉移至其他卡片」。

在這個範例中，Google Chat 應用程式會開啟初始對話方塊，引導使用者進入第二個對話方塊，確認後再提交：

Node.js

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(req.body));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openInitialDialog":
            return res.send(openInitialDialog(req.body));
        case "openConfirmationDialog":
            return res.send(openConfirmationDialog(req.body));
        case "submitDialog":
            return res.send(submitDialog(req.body));
    }
  }
};

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} response that handles dialogs.
 */
function handleMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openInitialDialog" }],
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{
          key: "actionName", value: "submitDialog" }, {
          // Pass input values as parameters for last dialog step (submission)
          key: "contactName", value: name
        }]
      }}
    }]}}]
  }]}}]}};
}

Apps Script

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

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        function: "openInitialDialog",
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [{ key: "contactName", value: name }]
      }}
    }]}}]
  }]}}]}};
}

其中 WIDGETS 代表任何其他表單輸入小工具。

關閉對話方塊

使用者點選對話方塊中的提交按鈕時，Chat 應用程式會執行相關聯的動作，並提供事件物件，且 buttonClickedPayload 會設為下列值：

isDialogEvent為 true。
dialogEventType為 SUBMIT_DIALOG。

Chat 應用程式應傳回 RenderActions 物件，並將 EndNavigation 設為 CLOSE_DIALOG。

選用：顯示暫時性通知

關閉對話方塊時，您也可以向與應用程式互動的使用者顯示臨時文字通知。

如要顯示通知，請傳回 RenderActions 物件，並設定 notification 欄位。

以下範例會檢查參數是否有效，並視結果關閉對話方塊，同時顯示文字通知：

Node.js

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Apps Script

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

如要瞭解如何在對話方塊之間傳遞參數，請參閱「將資料轉移至其他資訊卡」。

選用：傳送確認即時通訊訊息

關閉對話方塊後，您也可以傳送新的即時通訊訊息，或更新現有訊息。

如要傳送新訊息，請傳回 DataActions 物件，並將 CreateMessageAction 欄位設為新訊息。舉例來說，如要關閉對話方塊並傳送簡訊，請傳回下列內容：

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

如要在使用者提交對話方塊後更新訊息，請傳回 DataActions 物件，其中包含下列其中一項動作：

UpdateMessageAction：更新 Chat 應用程式傳送的訊息，例如使用者要求對話的訊息。
UpdateInlinePreviewAction：從連結預覽更新資訊卡。

疑難排解

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

即使 Chat 使用者介面未顯示錯誤訊息，只要開啟 Chat 應用程式的錯誤記錄功能，系統就會提供說明性錯誤訊息和記錄資料，協助您修正錯誤。如需查看、偵錯及修正錯誤的相關協助，請參閱「排解及修正 Google Chat 錯誤」。

建構互動式對話方塊 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

必要條件

HTTP

Apps Script

開啟對話方塊

觸發對話方塊要求

開啟初始對話方塊

處理對話方塊提交作業

選用：傳回其他對話方塊

Node.js

Apps Script

關閉對話方塊

選用：顯示暫時性通知

Node.js

Apps Script

選用：傳送確認即時通訊訊息

疑難排解

建構互動式對話方塊