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

為步驟建構設定卡片

本指南說明如何建構設定資訊卡，讓使用者自訂 Google Workspace Flows 中的步驟，並提供輸入內容。

一般來說，如要建構設定資訊卡，請像建構其他 Google Workspace 外掛程式一樣，建構資訊卡介面。如需建構設定卡片介面的說明，請參閱下列文章：

資訊卡建構工具：互動式工具，可協助您建構及定義資訊卡。
Google Workspace 外掛程式 API 參考說明文件中的「Card」。
Card Service：Apps Script 服務，可讓指令碼設定及建構資訊卡。
Google Workspace 外掛程式開發人員說明文件中的資訊卡式介面。

部分資訊卡小工具具有 Workspace Flows 專屬的功能，詳情請參閱本指南。

定義設定資訊卡

在 Apps Script 資訊清單和程式碼中定義設定資訊卡。

以下範例說明如何建構設定資訊卡，要求使用者選取 Google Chat 聊天室。

編輯資訊清單檔案

在資訊清單檔案中定義 workflowElements。

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Sample add-on",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/gsuite_addons/v6/web-24dp/logo_gsuite_addons_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Chat space selector",
          "description": "Lets the user select a space from Google  Chat",
          "workflowAction": {
            "inputs": [
              {
                "id": "chooseSpace",
                "description": "Choose a Chat space",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigSpacePicker",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

編輯程式碼

在應用程式程式碼中傳回卡片。

Apps Script

/**
* Generates and displays a configuration card to choose a Chat space
  */
function onConfigSpacePicker() {
  var card = {
    "sections": [
      {
        "header": "Choose a Chat space",
        "widgets": [
          {
            "selectionInput": {
              "name": "value1",
              "label": "First value",
              "type": "MULTI_SELECT",
              "platformDataSource": {
                "hostAppDataSource": {
                  "workflowDataSource": {
                    "includeVariables": true,
                    "type": "SPACE"
                  }
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

為輸入小工具設定自動完成功能

您可以為 SelectionInput小工具設定自動完成功能，協助使用者從選項清單中選取項目。舉例來說，如果使用者開始在會填入美國城市名稱的選單中輸入 Atl，您的元素可以在使用者輸入完畢前自動建議 Atlanta。最多可自動完成 100 個項目。

自動完成建議可能來自下列資料來源：

伺服器端自動完成：系統會根據您定義的第三方或外部資料來源，填入建議。
Google Workspace 資料：建議會從 Google Workspace 來源 (例如 Google Workspace 使用者或 Google Chat 空間) 填入。

伺服器端自動完成

您可以設定 SelectionInput 小工具，從外部資料來源自動完成建議。舉例來說，您可以協助使用者從客戶關係管理 (CRM) 系統的銷售待開發客戶清單中選取項目。

如要導入伺服器端自動完成功能，請按照下列步驟操作：

定義資料來源：在 SelectionInput 小工具中，新增指定 RemoteDataSource 的 DataSourceConfig。這項設定會指向擷取自動完成建議的 Apps Script 函式。
實作自動完成功能：使用者在輸入欄位中輸入內容時，系統會觸發這項功能。函式應根據使用者輸入內容查詢外部資料來源，並傳回建議清單。

以下範例說明如何為伺服器端自動完成功能設定 SelectionInput 小工具：

Apps Script

// In your onConfig function:
var multiSelect1 =
  CardService.newSelectionInput()
    .setFieldName("value1")
    .setTitle("Server Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setRemoteDataSource(
          CardService.newAction().setFunctionName('getAutocompleteResults')
        )
    )
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setPlatformDataSource(
          CardService.newPlatformDataSource()
            .setHostAppDataSource(
              CardService.newHostAppDataSource()
                .setWorkflowDataSource(
                  CardService.newWorkflowDataSource()
                    .setIncludeVariables(true)
                ))
        )
    );

// ... add widget to card ...

處理自動完成要求

setFunctionName 中指定的函式 (例如 getAutocompleteResults) 在使用者於欄位中輸入內容時，會收到事件物件。這個函式必須：

檢查 event.workflow.elementUiAutocomplete.invokedFunction，確認是否與預期的函式名稱相符。
從 event.workflow.elementUiAutocomplete.query 取得使用者輸入內容。
使用查詢查詢外部資料來源。
以必要格式傳回最多 100 則建議。

以下範例說明如何實作 handleAutocompleteRequest() 函式，根據使用者的查詢傳回建議：

Apps Script

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results based on the query
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

// In your onConfig function, handle the autocomplete event
function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // ... rest of your card building logic ...
}

Google Workspace 資料自動完成

您也可以從使用者 Google Workspace 環境中的資料填入自動完成建議：

Google Workspace 使用者：填入相同 Google Workspace 機構中的使用者。
Google Chat 聊天室：填入使用者所屬的 Google Chat 聊天室。

如要設定這項功能，請在 SelectionInput 小工具中設定 PlatformDataSource，並將 WorkflowDataSourceType 指定為 USER 或 SPACE。

Apps Script

// User Autocomplete
var multiSelect2 =
  CardService.newSelectionInput()
    .setFieldName("value2")
    .setTitle("User Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.USER)
            ))
    );

// Chat Space Autocomplete
var multiSelect3 =
  CardService.newSelectionInput()
    .setFieldName("value3")
    .setTitle("Chat Space Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            ))
    );

範例：合併自動完成類型

以下範例顯示 onConfig 函式，該函式會建立含有三個 SelectionInput 小工具的資訊卡，示範伺服器端、使用者和空間自動完成功能：

Apps Script

function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // Server-side autocomplete widget
  var multiSelect1 =
    CardService.newSelectionInput()
      .setFieldName("value1")
      .setTitle("Server Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .addDataSourceConfig(
        CardService.newDataSourceConfig()
          .setRemoteDataSource(
            CardService.newAction().setFunctionName('getAutocompleteResults')
          )
      )
      .addDataSourceConfig(
        CardService.newDataSourceConfig()
          .setPlatformDataSource(
            CardService.newPlatformDataSource()
              .setHostAppDataSource(
                CardService.newHostAppDataSource()
                  .setWorkflowDataSource(
                    CardService.newWorkflowDataSource()
                      .setIncludeVariables(true)
                  ))
          )
      );

  // User autocomplete widget
  var multiSelect2 =
    CardService.newSelectionInput()
      .setFieldName("value2")
      .setTitle("User Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.USER)
              ))
      );

  // Space autocomplete widget
  var multiSelect3 =
    CardService.newSelectionInput()
      .setFieldName("value3")
      .setTitle("Chat Space Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.SPACE)
              ))
      );

  var sectionBuilder =
    CardService.newCardSection()
      .addWidget(multiSelect1)
      .addWidget(multiSelect2)
      .addWidget(multiSelect3);

  var card =
    CardService.newCardBuilder()
      .addSection(sectionBuilder)
      .build();
  return card;
}

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

Workspace Flows 專屬功能

部分資訊卡小工具具有 Workspace Flows 專屬功能，詳情請參閱這篇文章。

TextInput 和 SelectionInput

TextInput 和 SelectionInput 小工具提供下列 Workspace Flows 專屬功能：

includeVariables：布林屬性，可讓使用者從先前的步驟選取變數。
type：列舉值，可自動完成建議。支援的值包括：
- USER：為使用者聯絡人中的人員提供自動完成建議。
- SPACE：為使用者所屬的 Google Chat 聊天室提供自動完成建議。

如果同時設定 includeVariables 和 type，輸入欄位會合併兩者的體驗。使用者可以從下拉式選單中選取相符的 type 變數，並查看自動完成建議。

圖 1：使用者在選擇空間時，會查看自動完成建議。
圖 2：使用者從「變數」➕ 下拉式選單中，選取上一個步驟的輸出變數。

資訊卡注意事項與限制

擴充 Flows 的外掛程式不支援卡片導覽，例如 popCard()、pushCard() 和 updateCard()。
在變數挑選器中使用 SelectionInput 時，小工具只支援 "type": "MULTI_SELECT"。在設定資訊卡的其他位置，SelectionInput 支援 SelectionType 的所有值。

為步驟建構設定卡片 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

定義設定資訊卡

編輯資訊清單檔案

JSON

編輯程式碼

Apps Script

為輸入小工具設定自動完成功能

伺服器端自動完成

Apps Script

處理自動完成要求

Apps Script

Google Workspace 資料自動完成

Apps Script

範例：合併自動完成類型

Apps Script

Workspace Flows 專屬功能

TextInput 和 SelectionInput

資訊卡注意事項與限制

相關主題

為步驟建構設定卡片