為步驟建構設定卡片

本指南說明如何建構設定資訊卡，讓使用者自訂 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) 系統的銷售待開發客戶清單中選取項目。

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

定義資料來源：在 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
  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 ...
}

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 小工具的資訊卡，示範伺服器端、使用者和空間自動完成功能：

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Autocomplete Demo",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "autocomplete_demo",
          "state": "ACTIVE",
          "name": "Autocomplete Demo",
          "description": "Provide autocompletion in input fields",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "A multi-select field with autocompletion",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigAutocomplete",
            "onExecuteFunction": "onExecuteAutocomplete"
          }
        }
      ]
    }
  }
}

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
  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();
}

自訂變數挑選器按鈕

您可以設定按鈕大小和標籤，自訂變數挑選器按鈕。

按鈕大小

如要設定按鈕大小，請使用 setVariableButtonSize()，並搭配下列其中一個 VariableButtonSize 列舉：

UNSPECIFIED：預設值。按鈕在側邊面板中會顯示精簡版，在其他情況下則會顯示完整版。
COMPACT：按鈕只會顯示加號 (+)。
FULL_SIZE：按鈕會顯示完整文字標籤。

按鈕標籤

如要設定按鈕文字，請使用 setVariableButtonLabel()。

範例：自訂變數選擇器

以下範例說明如何設定 TextInput 小工具，並使用不同大小的變數挑選器按鈕和自訂標籤。

圖 1：網頁上的變數選擇器按鈕自訂選項。
圖 2：外掛程式側邊面板中的變數選擇器按鈕自訂選項。

以下是自訂變數挑選器按鈕的資訊清單檔案：

JSON

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.locale"
  ],
  "addOns": {
    "common": {
      "name": "Variable button customization",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "variable_picker_customization",
          "state": "ACTIVE",
          "name": "Variable Picker demo",
          "description": "List all possible variable picker customization options",
          "workflowAction": {
            "onConfigFunction": "onUpdateCardConfigFunction",
            "onExecuteFunction": "onUpdateCardExecuteFunction"
          }
        }
      ]
    }
  }
}

以下是自訂變數挑選器按鈕的程式碼：

Apps Script

function onUpdateCardConfigFunction(event) {
  const textInput1 = CardService.newTextInput()
    .setFieldName("value1")
    .setTitle("Regular variable picker button")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
      )
    );

  const textInput2 = CardService.newTextInput()
    .setFieldName("value2")
    .setTitle("Size: Unspecified")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
      )
    );

  const textInput3 = CardService.newTextInput()
    .setFieldName("value3")
    .setTitle("Size: Full size")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonSize(CardService.VariableButtonSize.FULL_SIZE)
      )
    );

  const textInput4 = CardService.newTextInput()
    .setFieldName("value4")
    .setTitle("Size: Compact")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonSize(CardService.VariableButtonSize.COMPACT)
      )
    );

  const textInput5 = CardService.newTextInput()
    .setFieldName("value5")
    .setTitle("Custom button label")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonLabel("New button label!")
      )
    );

  var cardSection = CardService.newCardSection()
    .addWidget(textInput1)
    .addWidget(textInput2)
    .addWidget(textInput3)
    .addWidget(textInput4)
    .addWidget(textInput5)
    .setId("section_1");

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

  return card;
}

function onUpdateCardExecuteFunction(event) {
}

Workspace Studio 專屬功能

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

TextInput 和 SelectionInput

TextInput 和 SelectionInput 小工具具有下列 Workspace Studio 專屬功能：

includeVariables：布林值屬性，可讓使用者從先前的步驟選取變數。如要在後續步驟中顯示變數選擇器，起始事件和至少一個對應的輸出變數都必須對應至變數。
type：列舉值，可自動完成建議。支援的值包括：
- USER：為使用者聯絡人提供人員自動完成建議。
- SPACE：提供使用者所屬 Google Chat 聊天室的自動完成建議。

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

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

使用溢位選單選取一個輸出變數

您可以設定 SelectionInput 小工具，讓使用者透過溢位選單，從上一個步驟選取單一輸出變數。

將 SelectionInputType 設為 OVERFLOW_MENU 時，小工具會做為專用變數選擇器。與搭配 TextInput 使用 includeVariables 不同，後者會將變數值轉換為字串，而 OVERFLOW_MENU 則會保留所選變數的原始資料類型。

Apps Script

const selectionInput = CardService.newSelectionInput()
  .setFieldName("variable_picker_1")
  .setTitle("Variable Picker")
  .setType(
    CardService.SelectionInputType.OVERFLOW_MENU
  );

允許使用者合併文字和輸出變數

您可以設定 TextInput 小工具，控管使用者如何透過 setInputMode() 與文字和輸出變數互動。

RICH_TEXT：可讓使用者合併文字和輸出變數。結果是單一串連字串。
PLAIN_TEXT：限制輸入內容。使用者可以輸入文字或選取單一輸出變數。選取變數後，系統會取代所有現有文字。使用這個模式，強制執行資訊清單中定義的特定資料類型。

下圖顯示兩個 TextInput 小工具。第一個設定為 RICH_TEXT，並包含文字和輸出變數。第二個則設定為 PLAIN_TEXT，且只允許輸出變數。

圖 5：設定為 RICH_TEXT 和 PLAIN_TEXT 的文字輸入小工具。

建議您為所有 TextInput 小工具明確設定輸入模式。

以下是資訊清單檔案，用於設定具有不同輸入模式的 TextInput 小工具：

JSON

{
  "timeZone": "America/Toronto",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Text and output variable demo",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "richTextDemo",
          "state": "ACTIVE",
          "name": "Rich Text Demo",
          "description": "Show the difference between rich text and plain text TextInput widgets",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "First user input",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              },
              {
                "id": "value2",
                "description": "Second user input",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfiguration",
            "onExecuteFunction": "onExecution"
          }
        }
      ]
    }
  }
}

以下程式碼用於設定不同輸入模式的 TextInput 小工具：

Apps Script

function onConfiguration() {
  const input1 = CardService.newTextInput()
    .setFieldName("value1")
    .setId("value1")
    .setTitle("Rich Text")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    )
    // Set input mode to RICH_TEXT to allow mixed text and variables.
    .setInputMode(CardService.TextInputMode.RICH_TEXT);

  const input2 = CardService.newTextInput()
    .setFieldName("value2")
    .setId("value2")
    .setTitle("Plain text")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    )
    // Set input mode to PLAIN_TEXT to enforce single variable selection.
    .setInputMode(CardService.TextInputMode.PLAIN_TEXT);

  const section = CardService.newCardSection()
    .addWidget(input1)
    .addWidget(input2);

  const card = CardService.newCardBuilder()
    .addSection(section)
    .build();

  return card;
}

function onExecution(e) {
}

卡片注意事項與限制

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

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

定義設定卡片

編輯資訊清單檔案

JSON

編輯程式碼

Apps Script

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

伺服器端自動完成

Apps Script

處理自動完成要求

Apps Script

Google Workspace 資料自動完成

Apps Script

範例：合併自動完成類型

JSON

Apps Script

自訂變數挑選器按鈕

按鈕大小

按鈕標籤

範例：自訂變數選擇器

JSON

Apps Script

Workspace Studio 專屬功能

TextInput 和 SelectionInput

使用溢位選單選取一個輸出變數

Apps Script

允許使用者合併文字和輸出變數

JSON

Apps Script

卡片注意事項與限制

相關主題

為步驟建構設定卡片