此页面由 Cloud Translation API 翻译。

为步骤构建配置卡片

本指南介绍了如何构建配置卡片，以便用户自定义 Google Workspace Flows 中的某个步骤并为其提供输入。

一般来说，如需构建配置卡片，您需要像构建任何其他 Google Workspace 插件一样构建卡片界面。如需有关构建配置卡界面方面的帮助，请参阅以下内容：

卡片构建器，一种可帮助您构建和定义卡片的互动式工具。
Google Workspace 加载项 API 参考文档中的卡片。
卡片服务，一种 Apps 脚本服务，可让脚本配置和构建卡片。
Google Workspace 插件开发者文档中的基于卡片的界面。

部分卡片 widget 具有特定于 Workspace Flows 的特殊功能，本指南将详细介绍这些功能。

定义配置卡

在 Apps 脚本清单和代码中定义配置卡片。

以下示例展示了如何构建一个配置卡片，让用户选择 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 脚本

/**
* 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
      }]
    }
  };
}

为输入 widget 设置自动补全功能

您可以为 SelectionInput widget 配置自动补全功能，以帮助用户从选项列表中进行选择。例如，如果用户开始输入 Atl 以打开填充美国城市的菜单，您的元素可以在用户完成输入之前自动建议 Atlanta。您最多可以自动补全 100 个项目。

自动补全建议可能来自以下数据源：

服务器端自动补全：建议来自您定义的第三方或外部数据源。
Google Workspace 数据：建议来自 Google Workspace 来源，例如 Google Workspace 用户或 Google Chat 群组。

服务器端自动补全

您可以配置 SelectionInput widget，以根据外部数据源自动补全建议。例如，您可以帮助用户从客户关系管理 (CRM) 系统的销售线索列表中进行选择。

如需实现服务器端自动填充，您需要：

定义数据源：在 SelectionInput widget 中，添加指定 RemoteDataSource 的 DataSourceConfig。此配置指向用于获取自动补全建议的 Apps 脚本函数。
实现自动补全功能：当用户在输入字段中输入内容时，系统会触发此函数。该函数应根据用户输入查询外部数据源，并返回建议列表。

以下示例展示了如何为服务器端自动补全功能配置 SelectionInput widget：

Apps 脚本

// 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 脚本

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 widget 中设置 PlatformDataSource，并将 WorkflowDataSourceType 指定为 USER 或 SPACE。

Apps 脚本

// 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 widget 的卡片，演示了服务器端、用户和空间自动补全功能：

Apps 脚本

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 专用功能

某些卡片 widget 具有特定于 Workspace Flows 的特殊功能，详见此处。

TextInput 和 SelectionInput

TextInput 和 SelectionInput widget 具有以下 Workspace Flows 特有的功能：

includeVariables：一个布尔值属性，可让用户从之前的步骤中选择变量。
type：用于自动补全建议的枚举值。支持的值包括：
- USER：为用户联系人中的人员提供自动补全建议。
- SPACE：为用户所属的 Google Chat 聊天室提供自动补全建议。

如果同时设置了 includeVariables 和 type，输入字段会合并两者的体验。用户可以从下拉菜单中选择匹配的 type 变量，并查看该变量的自动补全建议。

图 1：用户在选择空间时查看自动补全建议。
图 2：用户从 ➕ 变量下拉菜单中选择上一步的输出变量。

卡注意事项和限制

扩展流程的插件不支持卡片导航，例如 popCard()、pushCard() 和 updateCard()。
当 SelectionInput 用于变量选择器时，widget 仅支持 "type": "MULTI_SELECT"。在配置卡的其他位置，SelectionInput 支持 SelectionType 的所有值。

为步骤构建配置卡片 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

定义配置卡

修改清单文件

JSON

修改代码

Apps 脚本

为输入 widget 设置自动补全功能

服务器端自动补全

Apps 脚本

处理自动补全请求

Apps 脚本

Google Workspace 数据自动补全

Apps 脚本

示例：组合自动补全类型

Apps 脚本

Workspace Flows 专用功能

TextInput 和 SelectionInput

卡注意事项和限制

相关主题

为步骤构建配置卡片