Z tego przewodnika dowiesz się, jak utworzyć zmienną wejściową.
Aby można było wykonać kroki, wymagane są określone informacje. Na przykład wysłanie e-maila wymaga podania adresu e-mail. Aby przekazać te niezbędne informacje, zdefiniuj zmienne wejściowe. Po zdefiniowaniu zmienne wejściowe są zwykle ustawiane przez użytkownika na karcie konfiguracji kroku podczas jego konfigurowania.
Zdefiniuj zmienną wejściową w 2 miejscach: w pliku manifestu dodatku i w kodzie za pomocą karty konfiguracji, na której użytkownicy mogą wpisywać wartości zmiennych wejściowych.
Zdefiniuj zmienną wejściową w pliku manifestu
W pliku manifestu określ zmienne wejściowe za pomocą tablicy inputs[]. Każdy element w tablicy inputs[] ma te właściwości:
id: unikalny identyfikator zmiennej wejściowej. Aby umożliwić przepływowi powiązanie elementu wejściowego karty konfiguracji z tą zmienną wejściową, musi on być zgodny z nazwą odpowiedniego elementu karty.description: opis zmiennej wejściowej, który będzie wyświetlany użytkownikom.cardinality: ile wartości jest dozwolonych. Możliwe wartości:SINGLE: dozwolona jest tylko jedna wartość.
dataType: typ akceptowanych wartości.dataTypema właściwośćbasicType, która określa typ danych. Prawidłowe wartości to:STRING: ciąg alfanumeryczny.INTEGER: liczba.TIMESTAMP: sygnatura czasowa w formacie „milisekundy od początku epoki systemu Unix”. Na przykład 27 listopada 2025 r., godz. 16:49:02 UTC jest reprezentowany jako1764262142988.BOOLEAN: wartość true lub false.EMAIL_ADDRESS: adres e-mail w formaciedana@example.com.
W tym przykładzie zdefiniowano 3 zmienne wejściowe dla kroku kalkulatora. Pierwsze 2 zmienne wejściowe to liczby całkowite, a trzecia to działanie arytmetyczne.
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"
}
}
]
}
}
}
Zdefiniuj zmienną wejściową w kodzie
Kod kroku zawiera funkcję o nazwie onConfigFunction(), która zwraca kartę konfiguracji definiującą 1 widżet karty wejściowej dla każdej zmiennej wejściowej zdefiniowanej w tablicy inputs[] w pliku manifestu.
Widżety wejściowe zdefiniowane na karcie konfiguracji muszą spełniać te wymagania:
- Wartość
namekażdego widżetu wejściowego musi być zgodna z odpowiednią wartościąidzmiennej wejściowej w pliku manifestu. - Kardynalność widżetu wejściowego musi być zgodna z kardynalnością zmiennej wejściowej
cardinalityw pliku manifestu. - Typ danych widżetu wejściowego musi być zgodny z typem danych zmiennej wejściowej
dataTypew pliku manifestu. Jeśli zmienna wejściowa ma typdataType, nie może zawierać ciągu znaków.
Aby uzyskać pomoc w tworzeniu interfejsów kart, skorzystaj z jednej z tych opcji:
- Kreator kart: interaktywne narzędzie, za pomocą którego możesz tworzyć i definiować karty.
- Karta: w dokumentacji referencyjnej interfejsu API dodatków do Google Workspace.
- Card Service: usługa Apps Script, która umożliwia skryptom konfigurowanie i tworzenie kart.
- Omówienie interfejsów opartych na kartach: w dokumentacji dla programistów dodatków do Google Workspace.
Poniższy przykład zwraca kartę konfiguracji dla każdego widżetu wejściowego zdefiniowanego w sekcji Zdefiniuj zmienną wejściową w pliku manifestu.
Google 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;
}
Używanie zmiennych wyjściowych z poprzednich kroków
Możesz skonfigurować zmienne wejściowe tak, aby akceptowały zmienne wyjściowe z poprzednich kroków przepływu pracy.
Włącz wybór zmiennych
Aby umożliwić użytkownikom wybieranie zmiennych z poprzednich kroków, użyj właściwości includeVariablesw widżetach TextInput i SelectionInput.
Widżety TextInput i SelectionInput mają te funkcje Workspace Studio:
includeVariables: właściwość logiczna, która umożliwia użytkownikom wybieranie zmiennych z poprzednich kroków. Aby w późniejszych krokach wyświetlić selektor zmiennych, zarówno zdarzenie początkowe, jak i co najmniej 1 odpowiadająca mu zmienna wyjściowa muszą być mapowane na zmienną.type: wartość wyliczeniowa, która automatycznie uzupełnia sugestie. Obsługiwane wartości to:USER: podaje sugestie autouzupełniania dotyczące osób z kontaktów użytkownika.SPACE: podaje sugestie autouzupełniania dotyczące pokoi w Google Chat, do których należy użytkownik.
Jeśli ustawisz zarówno includeVariables, jak i type, pole wejściowe połączy ich funkcje. Użytkownicy mogą wybrać zmienną pasującego type z menu i wyświetlić sugestie autouzupełniania.
-
Rysunek 4. Użytkownik sprawdza sugestie autouzupełniania podczas wybierania miejsca. -
Ilustracja 5. Użytkownik wybiera zmienną wyjściową z poprzedniego kroku w menu ➕Zmienne.
Wybieranie tylko jednej zmiennej wyjściowej za pomocą menu dodatkowego
Możesz skonfigurować SelectionInput
widżet, aby umożliwić użytkownikom wybieranie pojedynczej zmiennej wyjściowej
z poprzedniego kroku za pomocą menu dodatkowego.
Gdy ustawisz wartość SelectionInputType na OVERFLOW_MENU, widżet będzie działać jako dedykowany selektor zmiennych. W przeciwieństwie do używania includeVariables z TextInput, które konwertuje wartości zmiennych na ciągi znaków, OVERFLOW_MENU zachowuje oryginalny typ danych wybranej zmiennej.
Google Apps Script
const selectionInput = CardService.newSelectionInput()
.setFieldName("variable_picker_1")
.setTitle("Variable Picker")
.setType(
CardService.SelectionInputType.OVERFLOW_MENU
);
Zezwalanie użytkownikom na łączenie tekstu i zmiennych wyjściowych
Możesz skonfigurować TextInput widgety, aby określić, jak użytkownicy wchodzą w interakcje z tekstem i zmiennymi wyjściowymi za pomocą setInputMode().
RICH_TEXT: umożliwia użytkownikom łączenie tekstu i zmiennych wyjściowych. W wyniku otrzymasz jeden połączony ciąg znaków.PLAIN_TEXT: ogranicza wprowadzanie danych. Użytkownicy mogą wpisać tekst lub wybrać jedną zmienną wyjściową. Wybranie zmiennej spowoduje zastąpienie istniejącego tekstu. Użyj tego trybu, aby wymusić określone typy danych zdefiniowane w pliku manifestu.
Obraz poniżej przedstawia 2 widżety TextInput. Pierwsza jest skonfigurowana jako RICH_TEXT i zawiera tekst oraz zmienną wyjściową. Drugi jest skonfigurowany jako PLAIN_TEXT i umożliwia tylko zmienną wyjściową.
-
Ilustracja 3. Widżety wprowadzania tekstu skonfigurowane jako RICH_TEXTiPLAIN_TEXT.
Zalecamy jawne ustawienie trybu wprowadzania dla wszystkich widżetów TextInput.
Oto plik manifestu do konfigurowania widżetów TextInput z różnymi trybami wprowadzania:
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"
}
}
]
}
}
}
Oto kod do konfigurowania widżetów TextInput z różnymi trybami wprowadzania:
Google 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) {
}
Dostosowywanie przycisków selektora zmiennych
Możesz dostosować przycisk selektora zmiennych, ustawiając jego rozmiar i etykietę.
Rozmiar przycisku
Aby ustawić rozmiar przycisku, użyj elementu setVariableButtonSize() z jedną z tych wartości typu enum VariableButtonSize:
UNSPECIFIED: wartość domyślna. Przycisk jest kompaktowy w panelu bocznym i pełnowymiarowy w innych kontekstach.COMPACT: przycisk wyświetla tylko znak plusa (+).FULL_SIZE: przycisk wyświetla pełną etykietę tekstową.
Etykieta przycisku
Aby ustawić tekst przycisku, użyj setVariableButtonLabel().
Przykład: dostosowywanie selektora zmiennych
Poniższy przykład pokazuje, jak skonfigurować widżety TextInput z przyciskami wyboru zmiennych o różnych rozmiarach i niestandardową etykietą.
-
Rysunek 1. Dostosowywanie przycisku selektora zmiennych w internecie. -
Rysunek 2. Dostosowywanie przycisku wyboru zmiennej w panelu bocznym dodatku.
Oto plik manifestu do dostosowywania przycisków selektora zmiennych:
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"
}
}
]
}
}
}
Oto kod do dostosowywania przycisków selektora zmiennych:
Google 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) {
}
Konfigurowanie autouzupełniania danych Google Workspace
Możesz też wypełniać sugestie autouzupełniania danymi z środowiska Google Workspace użytkownika:
- Użytkownicy Google Workspace: wypełnij listę użytkowników w tej samej organizacji Google Workspace.
- Pokoje Google Chat: wypełniaj pokoje Google Chat, których użytkownik jest członkiem.
Aby to skonfigurować, ustaw wartość parametru PlatformDataSource w widżecie SelectionInput, określając wartość parametru WorkflowDataSourceType jako USER lub SPACE.
Google 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)
))
);
Przykład: łączenie typów autouzupełniania
Przykład poniżej pokazuje funkcję onConfig, która tworzy kartę z 3 widgetami SelectionInput. Demonstruje ona autouzupełnianie po stronie serwera, użytkownika i przestrzeni:
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"
}
}
]
}
}
}
Google 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();
}
Sprawdź zmienną wejściową
Sprawdzoną metodą jest weryfikowanie, czy użytkownik wprowadza odpowiednią wartość. Zobacz Weryfikowanie zmiennej wejściowej.
Powiązane artykuły
- Sprawdzanie poprawności zmiennej wejściowej
- Zmienne wyjściowe
- Zmienne dynamiczne
- Rejestrowanie aktywności i błędów
- Obiekty zdarzeń Workspace Studio