Z tego przewodnika dowiesz się, jak utworzyć zmienną wejściową.
Aby można było wykonać działania, wymagane są określone informacje. Na przykład do wysłania e-maila potrzebny jest adres 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 działania 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.
Definiowanie zmiennej wejściowej 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 odpowiadać nazwie odpowiedniego elementu karty.description: opis zmiennej wejściowej, który ma być wyświetlany użytkownikom.cardinality: liczba dozwolonych wartości. Możliwe wartości:SINGLE: dozwolona jest tylko 1 wartość.
dataType: typ akceptowanych wartości.dataTypema właściwośćbasicType, która określa typ danych. Prawidłowe wartości:STRING: ciąg alfanumeryczny.INTEGER: liczba.TIMESTAMP: sygnatura czasowa w formacie „milisekundy od początku czasu uniksowego”. Na przykład 27 listopada 2025 r. o 16:49:02 UTC jest reprezentowany jako1764262142988.BOOLEAN: wartość true lub false.EMAIL_ADDRESS: adres e-mail w formaciedana@example.com.
Poniższy przykład definiuje 3 zmienne wejściowe dla działania kalkulatora. Pierwsze 2 zmienne wejściowe to liczby całkowite, a trzecia to operacja arytmetyczna.
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"
}
}
]
}
}
}
Definiowanie zmiennej wejściowej w kodzie
Kod działania 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[] pliku manifestu.
Widżety wejściowe zdefiniowane na karcie konfiguracji muszą spełniać te wymagania:
namekażdego widżetu wejściowego musi odpowiadać jegoidzmiennej wejściowej w pliku manifestu.- Liczność widżetu wejściowego musi odpowiadać liczności
cardinalityzmiennej wejściowej w pliku manifestu. - Typ danych widżetu wejściowego musi odpowiadać typowi danych
dataTypezmiennej wejściowej w pliku manifestu. Jeśli zmienna wejściowa ma typ danychdataTypejako liczbę całkowitą, nie może zawierać ciągu znaków.
Aby uzyskać pomoc w tworzeniu interfejsów kart, zapoznaj się z jedną z tych opcji:
- Kreator kart: interaktywne narzędzie za pomocą którego możesz tworzyć i definiować karty.
- Karta: w dokumentacji referencyjnej interfejsu Google Workspace API documentation.
- Usługa kart: 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 Definiowanie zmiennej wejściowej w pliku manifestu.
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 działań
Możesz skonfigurować zmienne wejściowe tak, aby akceptowały zmienne wyjściowe z poprzednich działań w przepływie pracy.
Włączanie wyboru zmiennych
Aby umożliwić użytkownikom wybieranie zmiennych z poprzednich działań, użyj właściwości includeVariables w widżetach TextInput i SelectionInput.
Widżety TextInput i SelectionInput mają te funkcje specyficzne dla Workspace Studio:
includeVariables: właściwość logiczna, która umożliwia użytkownikom wybieranie zmiennych z poprzednich działań. Aby selektor zmiennych wyświetlał się w kolejnych działaniach, zarówno zdarzenie początkowe, jak i co najmniej 1 odpowiednia zmienna wyjściowa muszą być powiązane ze zmienną.type: wyliczona wartość, która automatycznie uzupełnia sugestie. Obsługiwane wartości:USER: wyświetla sugestie autouzupełniania dla osób w kontaktach użytkownika.SPACE: wyświetla sugestie autouzupełniania dla pokoi Google Chat, których użytkownik jest członkiem.
Gdy ustawione są zarówno includeVariables, jak i type, pole do wprowadzania danych łączy ich funkcje. Użytkownicy mogą wybrać zmienną pasującego type z menu i wyświetlać dla niej sugestie autouzupełniania.
-
Ilustracja 4. Użytkownik sprawdza sugestie autouzupełniania podczas wybierania pokoju. -
Ilustracja 5. Użytkownik wybiera zmienną wyjściową poprzedniego działania z menu ➕Zmienne.
Wybieranie tylko 1 zmiennej wyjściowej za pomocą menu rozszerzonego
Możesz skonfigurować SelectionInput
widżet tak, aby użytkownicy mogli wybrać 1 zmienną wyjściową
z poprzedniego działania za pomocą menu rozszerzonego.
Gdy ustawisz SelectionInputType na OVERFLOW_MENU, widżet będzie służyć 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.
Apps Script
const selectionInput = CardService.newSelectionInput()
.setFieldName("variable_picker_1")
.setTitle("Variable Picker")
.setType(
CardService.SelectionInputType.OVERFLOW_MENU
);
Umożliwianie użytkownikom łączenia tekstu i zmiennych wyjściowych
Możesz skonfigurować TextInput
widżety, aby kontrolować, 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. Wynikiem jest 1 połączony ciąg znaków.PLAIN_TEXT: ogranicza dane wejściowe. Użytkownicy mogą wpisać tekst lub wybrać 1 zmienną wyjściową. Wybranie zmiennej zastępuje cały dotychczasowy tekst. Użyj tego trybu, aby wymusić określone typy danych zdefiniowane w manifeście.
Obraz poniżej przedstawia 2 widżety TextInput. Pierwszy jest skonfigurowany jako RICH_TEXT i zawiera tekst oraz zmienną wyjściową. Drugi jest skonfigurowany jako PLAIN_TEXT i dopuszcza tylko zmienną wyjściową.
-
Ilustracja 3. Widżety wprowadzania tekstu skonfigurowane jako RICH_TEXTiPLAIN_TEXT.
Zalecamy wyraźne 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:
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 setVariableButtonSize z jedną z tych wyliczeń VariableButtonSize:
UNSPECIFIED: wartość domyślna. Przycisk jest kompaktowy w panelu bocznym i ma pełny rozmiar 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 różnymi rozmiarami przycisków selektora zmiennych i etykietą niestandardową.
-
Ilustracja 1. Dostosowywanie przycisku selektora zmiennych w internecie. -
Ilustracja 2. Dostosowywanie przycisku selektora zmiennych 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:
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 ze środowiska Google Workspace użytkownika:
- Użytkownicy Google Workspace: wypełniaj 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
PlatformDataSource
w widżecie
SelectionInput, określając
WorkflowDataSourceType
jako USER lub 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)
))
);
Przykład: łączenie typów autouzupełniania
Poniższy przykład pokazuje funkcję onConfig, która tworzy kartę z
3 SelectionInput
widżetami, demonstrując autouzupełnianie po stronie serwera, użytkownika i pokoju:
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();
}
Sprawdzanie poprawności zmiennej wejściowej
Zalecamy sprawdzenie, czy użytkownik wpisuje odpowiednią wartość. Więcej informacji znajdziesz w artykule Sprawdzanie poprawności 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