本指南介绍了如何创建输入变量。
若要运行，步骤需要某些信息。例如，发送电子邮件需要电子邮件地址。如需提供此必要信息，请定义输入变量。定义后，输入变量通常由用户在步骤的配置卡上设置，同时用户也会设置该步骤。
在两个位置定义输入变量：插件的清单文件，以及包含配置卡的相应代码（用户可在其中输入输入变量的值）。
在清单文件中定义输入变量
在清单文件中，使用 inputs[] 数组指定输入变量。inputs[] 数组中的每个项都具有以下属性：
id：输入变量的唯一标识符。为了让流程将配置卡输入元素与此输入变量相关联，必须与相应卡元素的名称一致。description：要向最终用户显示的输入变量的说明。cardinality：允许的值数量。可能的值包括：SINGLE：仅允许一个值。
dataType：接受的值类型。dataType具有用于定义数据类型的属性basicType。有效值包括：STRING：一个字母数字字符串。INTEGER：一个数字。TIMESTAMP：采用 ISO 8601 格式的时间戳。例如，在 ISO 8601 中，2025 年 3 月 15 日表示为 2025-03-15。BOOLEAN：true 或 false。EMAIL_ADDRESS：电子邮件地址，格式为dana@example.com。
以下示例为计算器步骤定义了三个输入变量。前两个输入变量是整数，第三个是算术运算。
JSON
{
"timeZone": "America/Los_Angeles",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Calculator",
"logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "actionElement",
"state": "ACTIVE",
"name": "Calculate",
"description": "Asks the user for two values and a math operation, then performs the math operation on the values and outputs the result.",
"workflowAction": {
"inputs": [
{
"id": "value1",
"description": "value1",
"cardinality": "SINGLE",
"dataType": {
"basicType": "INTEGER"
}
},
{
"id": "value2",
"description": "value2",
"cardinality": "SINGLE",
"dataType": {
"basicType": "INTEGER"
}
},
{
"id": "operation",
"description": "operation",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"outputs": [
{
"id": "result",
"description": "Calculated result",
"cardinality": "SINGLE",
"dataType": {
"basicType": "INTEGER"
}
}
],
"onConfigFunction": "onConfigCalculate",
"onExecuteFunction": "onExecuteCalculate"
}
}
]
}
}
}
在代码中定义输入变量
此步骤的代码包含一个名为 onConfigFunction() 的函数，该函数会返回一个配置卡片，其中为清单文件的 inputs[] 数组中定义的每个输入变量定义一个输入卡片 widget。
配置卡片中定义的输入 widget 具有以下要求：
- 每个输入 widget 的
name都必须与清单文件中相应输入变量的id相匹配。 - 输入 widget 的基数必须与清单文件中输入变量的
cardinality相匹配。 - 输入 widget 的数据类型必须与清单文件中的输入变量的
dataType相匹配。如果输入变量的dataType为整数，则不能包含字符串。
如需有关构建卡片界面的帮助，请参阅以下选项之一：
- 卡片构建器：一种可用于构建和定义卡片的交互式工具。
- 卡片：位于 Google Workspace 插件 API 参考文档中。
- 卡片服务：一种 Apps 脚本服务，可让脚本配置和构建卡片。
- 基于卡片的界面概览：位于 Google Workspace 插件开发者文档中。
以下示例会针对 在清单文件中定义输入变量中定义的每个输入 widget 返回一个配置卡片。
Apps 脚本
/**
* Generates and displays a configuration card for the sample calculation step.
*
* This function creates a card with input fields for two values and a drop-down
* for selecting an arithmetic operation. The card also includes a "Save"
* button to save the step configuration for the workflow.
*
* The input fields are configured to let the user select outputs from previous
* workflow steps as input values using the `hostAppDataSource` property.
*/
function onConfigFunction() {
var card = {
"sections": [
{
"header": "Step example: Calculate",
"widgets": [
{
"textInput": {
"name": "value1", // "name" must match an "id" in the manifest file's inputs[] array.
"label": "First value",
"hostAppDataSource" : {
"workflowDataSource" : {
"includeVariables" : true
}
}
}
},
{
"selectionInput": {
"name": "operation", // "name" must match an "id" in the manifest file's inputs[] array.
"label": "Operation",
"type": "DROPDOWN",
"items": [
{
"text": "+",
"value": "+",
},
{
"text": "-",
"value": "-",
},
{
"text": "x",
"value": "x",
},
{
"text": "/",
"value": "/",
}
]
}
},
{
"textInput": {
"name": "value2", // "name" must match an "id" in the manifest file's inputs[] array.
"label": "Second value",
"hostAppDataSource" : {
"workflowDataSource" : {
"includeVariables" : true
}
}
}
}
]
}
]
};
return {
"action": {
"navigations": [{
"push_card": card
}]
}
};
}
验证输入变量
最佳实践是验证用户输入的值是否合适。请参阅验证输入变量。