為步驟建構設定卡片

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

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

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

部分資訊卡小工具提供 Workspace Studio 專屬功能，詳情請參閱本指南。

定義設定卡片

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

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

編輯資訊清單檔案

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

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Chat space selector",
      "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": "onExecuteSpacePicker"
          }
        }
      ]
    }
  }
}

編輯程式碼

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

Apps Script

/**
 * Generates and displays a configuration card to choose a Chat space
 */
function onConfigSpacePicker() {

  const selectionInput = CardService.newSelectionInput()
    .setTitle("First Value")
    .setFieldName("chooseSpace")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            )
        )
    );

  const cardSection = CardService.newCardSection()
    .setHeader("Select Chat Space")
    .setId("section_1")
    .addWidget(selectionInput)

  var card = CardService.newCardBuilder()
    .addSection(cardSection)
    .build();

  return card;
}

function onExecuteSpacePicker(e) {
}

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

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

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

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

伺服器端自動完成

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

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

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

以下範例說明如何為伺服器端自動完成功能設定 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) 在使用者於欄位中輸入內容時，會收到事件物件。這個函式必須：

  1. 檢查 event.workflow.elementUiAutocomplete.invokedFunction，確認是否與預期的函式名稱相符。
  2. 從 event.workflow.elementUiAutocomplete.query 取得使用者輸入內容。
  3. 使用查詢查詢外部資料來源。
  4. 以必要格式傳回最多 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
  let autocompleteResponse = AddOnsResponseService.newUpdateWidget()
    .addSuggestion(
      query + " option 1",
      query + "_option1",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 1 bottom text"
    )
    .addSuggestion(
      query + " option 2",
      query + "_option2",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 2 bottom text"
    ).addSuggestion(
      query + " option 3",
      query + "_option3",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 3 bottom text"
    );

  const modifyAction = AddOnsResponseService.newAction()
    .addModifyCard(
      AddOnsResponseService.newModifyCard()
        .setUpdateWidget(autocompleteResponse)
    );

  return AddOnsResponseService.newRenderActionBuilder()
    .setAction(modifyAction)
    .build();
}

// 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 ...
}

卡片注意事項與限制