In dieser Anleitung wird beschrieben, wie Sie eine Eingabevariable erstellen.
Für die Ausführung von Schritten sind bestimmte Informationen erforderlich. Zum Senden einer E‑Mail ist beispielsweise eine E‑Mail-Adresse erforderlich. Um diese Informationen bereitzustellen, müssen Sie Eingabevariablen definieren. Nachdem sie definiert wurden, werden Eingabevariablen in der Regel vom Nutzer auf der Konfigurationskarte eines Schritts festgelegt, während er den Schritt einrichtet.
Definieren Sie die Eingabevariable an zwei Stellen: in der Manifestdatei des Add-ons und im Code mit einer Konfigurationskarte, auf der Nutzer Werte für Eingabevariablen eingeben können.
Eingabevariable in der Manifestdatei definieren
Geben Sie in der Manifestdatei Eingabevariablen mit dem Array inputs[] an. Jedes Element im inputs[]-Array hat die folgenden Attribute:
id: Eindeutige Kennung für eine Eingabevariable. Damit der Ablauf ein Konfigurationskarten-Eingabeelement mit dieser Eingabevariablen verknüpfen kann, muss der Name mit dem Namen des entsprechenden Kartenelements übereinstimmen.description: Eine Beschreibung der Eingabevariable, die Endnutzern angezeigt wird.cardinality: Wie viele Werte zulässig sind. Mögliche Werte:SINGLE: Es ist nur ein Wert zulässig.
dataType: Der Typ der akzeptierten Werte.dataTypehat das AttributbasicType, das den Datentyp definiert. Gültige Werte sind:STRING: Ein alphanumerischer String.INTEGER: Eine Zahl.TIMESTAMP: Ein Zeitstempel im Format „Millisekunden seit Unix-Epoche“. Der 27. November 2025, 16:49:02 Uhr UTC, wird beispielsweise als1764262142988dargestellt.BOOLEAN: entweder „true“ oder „false“.EMAIL_ADDRESS: Eine E-Mail-Adresse im Formatdana@example.com.
Im folgenden Beispiel werden drei Eingabevariablen für einen Berechnungsschritt definiert. Die ersten beiden Eingabevariablen sind Ganzzahlen und die dritte ist eine arithmetische Operation.
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": "calculatorDemo",
"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"
}
}
]
}
}
}
Eingabevariable im Code definieren
Der Code des Schritts enthält eine Funktion namens onConfigFunction(), die eine Konfigurationskarte zurückgibt, die ein Eingabekarten-Widget für jede Eingabevariable definiert, die im inputs[]-Array der Manifestdatei definiert ist.
Für die in der Konfigurationskarte definierten Eingabe-Widgets gelten die folgenden Anforderungen:
- Die
namejedes Eingabe-Widgets muss mit deridder entsprechenden Eingabevariable in der Manifestdatei übereinstimmen. - Die Kardinalität des Eingabe-Widgets muss mit dem
cardinalityder Eingabevariable in der Manifestdatei übereinstimmen. - Der Datentyp des Eingabe-Widgets muss mit dem
dataTypeder Eingabevariable in der Manifestdatei übereinstimmen. Wenn die Eingabevariable den TypdataType(Ganzzahl) hat, kann sie keinen String enthalten.
Hilfe beim Erstellen von Kartenoberflächen finden Sie in einer der folgenden Optionen:
- Card Builder: Ein interaktives Tool, mit dem Sie Karten erstellen und definieren können.
- Karte: in der Referenzdokumentation zur Google Workspace-Add-on-API.
- Card Service: Ein Apps Script-Dienst, mit dem Skripts Karten konfigurieren und erstellen können.
- Übersicht über kartenbasierte Benutzeroberflächen: in der Entwicklerdokumentation für Google Workspace-Add-ons.
Im folgenden Beispiel wird für jedes Eingabe-Widget, das in Eingabevariable in der Manifestdatei definieren definiert ist, eine Konfigurationskarte zurückgegeben.
Apps Script
/**
* 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 input fields are configured to let the user select outputs from previous
* workflow steps as input values using the `hostAppDataSource` property.
*/
function onConfigCalculate() {
const firstInput = CardService.newTextInput()
.setFieldName("value1") // "FieldName" must match an "id" in the manifest file's inputs[] array.
.setTitle("First Value")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
);
const secondInput = CardService.newTextInput()
.setFieldName("value2") // "FieldName" must match an "id" in the manifest file's inputs[] array.
.setTitle("Second Value")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
);
const selectionInput = CardService.newSelectionInput()
.setTitle("operation")
.setFieldName("operation") // "FieldName" must match an "id" in the manifest file's inputs[] array.
.setType(CardService.SelectionInputType.DROPDOWN)
.addItem("+", "+", false)
.addItem("-", "-", true)
.addItem("x", "x", false)
.addItem("/", "/", false);
const sections = CardService.newCardSection()
.setHeader("Action_sample: Calculate")
.setId("section_1")
.addWidget(firstInput)
.addWidget(selectionInput)
.addWidget(secondInput)
let card = CardService.newCardBuilder()
.addSection(sections)
.build();
return card;
}
Ausgabevariablen aus vorherigen Schritten verwenden
Sie können Eingabevariablen so konfigurieren, dass sie Ausgabevariablen aus vorherigen Schritten im Workflow akzeptieren.
Variablenauswahl aktivieren
Wenn Nutzer Variablen aus vorherigen Schritten auswählen sollen, verwenden Sie die includeVariables-Eigenschaft in TextInput- und SelectionInput-Widgets.
Die Widgets TextInput und SelectionInput haben die folgenden Workspace Studio-spezifischen Funktionen:
includeVariables: Eine boolesche Property, mit der Nutzer Variablen aus vorherigen Schritten auswählen können. Damit die Variablenauswahl in späteren Schritten angezeigt wird, müssen sowohl das Start- als auch mindestens ein entsprechendes Ausgabeereignis der Variablen zugeordnet sein.type: Ein aufgezählter Wert, der Vorschläge automatisch vervollständigt. Unterstützte Werte:USER: Bietet automatisch vervollständigte Vorschläge für Personen in den Kontakten des Nutzers.SPACE: Bietet Vorschläge für die automatische Vervollständigung für Google Chat-Gruppenbereiche, in denen der Nutzer Mitglied ist.
Wenn sowohl includeVariables als auch type festgelegt sind, werden die beiden Erfahrungen im Eingabefeld kombiniert. Nutzer können eine Variable des entsprechenden type aus einem Drop-down-Menü auswählen und Vorschläge zur automatischen Vervollständigung dafür aufrufen.
-
Abbildung 4:Ein Nutzer sieht sich Autocomplete-Vorschläge an, wenn er einen Bereich auswählt. -
Abbildung 5:Ein Nutzer wählt die Ausgabevariable eines vorherigen Schritts aus dem Drop-down-Menü „➕Variablen“ aus.
Nur eine Ausgabevariable mit einem Dreipunkt-Menü auswählen
Sie können ein SelectionInput-Widget so konfigurieren, dass Nutzer über ein Überlaufmenü eine einzelne Ausgabevariable aus einem vorherigen Schritt auswählen können.
Wenn Sie SelectionInputType auf OVERFLOW_MENU setzen, dient das Widget als spezielle Variablenauswahl. Im Gegensatz zur Verwendung von includeVariables mit TextInput, bei der Variablenwerte in Strings konvertiert werden, wird bei OVERFLOW_MENU der ursprüngliche Datentyp der ausgewählten Variablen beibehalten.
Apps Script
const selectionInput = CardService.newSelectionInput()
.setFieldName("variable_picker_1")
.setTitle("Variable Picker")
.setType(
CardService.SelectionInputType.OVERFLOW_MENU
);
Nutzern erlauben, Text und Ausgabevariablen zu kombinieren
Sie können TextInput-Widgets konfigurieren, um zu steuern, wie Nutzer mit Text und Ausgabevariablen über setInputMode() interagieren.
RICH_TEXT: Nutzer können Text und Ausgabevariablen kombinieren. Das Ergebnis ist ein einzelner verketteter String.PLAIN_TEXT: Schränkt die Eingabe ein. Nutzer können entweder Text eingeben oder eine einzelne Ausgabevariable auswählen. Wenn Sie eine Variable auswählen, wird der vorhandene Text ersetzt. In diesem Modus werden bestimmte im Manifest definierte Datentypen erzwungen.
Die folgende Abbildung zeigt zwei TextInput-Widgets. Die erste ist als RICH_TEXT konfiguriert und enthält Text und eine Ausgabevariable. Die zweite ist als PLAIN_TEXT konfiguriert und lässt nur eine Ausgabevariable zu.
-
Abbildung 3:Als RICH_TEXTundPLAIN_TEXTkonfigurierte Text-Eingabewidgets.
Wir empfehlen, den Eingabemodus für alle TextInput-Widgets explizit festzulegen.
Hier ist die Manifestdatei zum Konfigurieren von TextInput-Widgets mit verschiedenen Eingabemodi:
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"
}
}
]
}
}
}
Hier ist der Code zum Konfigurieren von TextInput-Widgets mit verschiedenen Eingabemodi:
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) {
}
Schaltflächen für die Variablenauswahl anpassen
Sie können die Schaltfläche zur Variablenauswahl anpassen, indem Sie die Schaltflächengröße und das Label festlegen.
Schaltflächengröße
Verwenden Sie setVariableButtonSize() mit einer der folgenden VariableButtonSize-Aufzählungen, um die Schaltflächengröße festzulegen:
UNSPECIFIED: Der Standardwert. Die Schaltfläche ist in der Seitenleiste kompakt und in anderen Kontexten in voller Größe zu sehen.COMPACT: Auf der Schaltfläche wird nur ein Pluszeichen (+) angezeigt.FULL_SIZE: Auf der Schaltfläche wird das vollständige Textlabel angezeigt.
Schaltflächenlabel
Verwenden Sie setVariableButtonLabel(), um den Schaltflächentext festzulegen.
Beispiel: Anpassung der Variablenauswahl
Im folgenden Beispiel sehen Sie, wie Sie TextInput-Widgets mit unterschiedlichen Schaltflächengrößen für die Variablenauswahl und einem benutzerdefinierten Label konfigurieren.
-
Abbildung 1:Anpassung der Schaltfläche zur Variablenauswahl im Web -
Abbildung 2:Anpassung der Schaltfläche zur Variablenauswahl in der Seitenleiste eines Add-ons.
Hier ist die Manifestdatei zum Anpassen der Schaltflächen für die Variablenauswahl:
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"
}
}
]
}
}
}
Hier ist der Code zum Anpassen der Schaltflächen für die Variablenauswahl:
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) {
}
Automatische Vervollständigung von Google Workspace-Daten konfigurieren
Sie können auch Vorschläge für die automatische Vervollständigung aus Daten in der Google Workspace-Umgebung des Nutzers generieren:
- Google Workspace-Nutzer:Nutzer in derselben Google Workspace-Organisation einfügen.
- Google Chat-Bereiche:Füllen Sie Google Chat-Bereiche aus, in denen der Nutzer Mitglied ist.
Konfigurieren Sie dazu im Widget SelectionInput das Feld PlatformDataSource und geben Sie für WorkflowDataSourceType entweder USER oder SPACE an.
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)
))
);
Beispiel: Autocomplete-Typen kombinieren
Das folgende Beispiel zeigt eine onConfig-Funktion, die eine Karte mit drei SelectionInput-Widgets erstellt. Sie demonstriert die serverseitige, nutzerbezogene und bereichsbezogene automatische Vervollständigung:
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();
}
Eingabevariable validieren
Als Best Practice sollten Sie prüfen, ob der Nutzer einen geeigneten Wert eingibt. Weitere Informationen finden Sie unter Eingabevariable validieren.
Weitere Informationen
- Eingabevariable validieren
- Ausgabevariablen
- Dynamische Variablen
- Aktivitäten und Fehler protokollieren
- Workspace Studio-Ereignisobjekte