Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Raccogliere dati con una variabile di input

Questa guida spiega come creare una variabile di input.

Per l'esecuzione, i passaggi richiedono determinate informazioni. Ad esempio, l'invio di un'email richiede un indirizzo email. Per fornire queste informazioni necessarie ai passaggi, definisci le variabili di input. Una volta definite, le variabili di input vengono in genere impostate dall'utente nella scheda di configurazione di un passaggio durante la configurazione del passaggio.

Definisci la variabile di input in due posizioni: nel file manifest del componente aggiuntivo e nel codice con una scheda di configurazione in cui gli utenti possono inserire i valori per le variabili di input.

Definisci la variabile di input nel file manifest

Nel file manifest, specifica le variabili di input con l'array inputs[]. Ogni elemento dell'array inputs[] ha le seguenti proprietà:

id: identificatore univoco per una variabile di input. Per consentire al flusso di associare un elemento di input della scheda di configurazione a questa variabile di input, deve corrispondere al nome dell'elemento della scheda corrispondente.
description: una descrizione della variabile di input da mostrare agli utenti finali.
cardinality: il numero di valori consentiti. I valori possibili sono:
- SINGLE: è consentito un solo valore.
dataType: il tipo di valori accettati. dataType ha la proprietà basicType che definisce il tipo di dati. I valori validi includono:
- STRING: una stringa alfanumerica.
- INTEGER: un numero.
- TIMESTAMP: un timestamp nel formato "millisecondi dall'epoca Unix". Ad esempio, il 27 novembre 2025, 16:49:02 UTC è rappresentato come 1764262142988.
- BOOLEAN: true o false.
- EMAIL_ADDRESS: un indirizzo email nel formato dana@example.com.

L'esempio seguente definisce tre variabili di input per un passaggio del calcolatore. Le prime due variabili di input sono numeri interi, mentre la terza è un'operazione aritmetica.

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"
          }
        }
      ]
    }
  }
}

Definisci la variabile di input nel codice

Il codice del passaggio include una funzione denominata onConfigFunction() che restituisce una scheda di configurazione che definisce un widget della scheda di input per ogni variabile di input definita nell'array inputs[] del file manifest.

I widget di input definiti nella scheda di configurazione hanno i seguenti requisiti:

Il name di ogni widget di input deve corrispondere all'id della variabile di input corrispondente nel file manifest.
La cardinalità del widget di input deve corrispondere alla cardinality della variabile di input nel file manifest.
Il tipo di dati del widget di input deve corrispondere al dataType della variabile di input nel file manifest. Se la variabile di input ha un dataType di tipo integer, non può contenere una stringa.

Per assistenza nella creazione di interfacce delle schede, consulta una delle seguenti opzioni:

Il generatore di schede: uno strumento interattivo che puoi utilizzare per creare e definire le schede.
Scheda: nella documentazione di riferimento dell'API dei componenti aggiuntivi di Google Workspace.
Servizio Schede: un servizio Apps Script che consente agli script di configurare e creare schede.
Panoramica delle interfacce basate su schede: in nella documentazione per gli sviluppatori di componenti aggiuntivi di Google Workspace.

L'esempio seguente restituisce una scheda di configurazione per ogni widget di input definito in Definisci la variabile di input nel file manifest.

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;
}

Utilizza le variabili di output dei passaggi precedenti

Puoi configurare le variabili di input in modo che accettino le variabili di output dei passaggi precedenti del workflow.

Abilita la selezione delle variabili

Per consentire agli utenti di selezionare le variabili dei passaggi precedenti, utilizza la proprietà includeVariables nei widget TextInput e SelectionInput.

I widget TextInput e SelectionInput hanno le seguenti funzionalità specifiche di Workspace Studio:

includeVariables: una proprietà booleana che consente agli utenti di selezionare le variabili dei passaggi precedenti. Affinché il selettore di variabili venga visualizzato nei passaggi successivi, sia l' evento iniziale sia almeno una variabile di output corrispondente devono essere mappati alla variabile.
type: un valore enumerato che completa automaticamente i suggerimenti. I valori supportati includono:
- USER: fornisce suggerimenti di completamento automatico per le persone nei contatti dell'utente.
- SPACE: fornisce suggerimenti di completamento automatico per gli spazi di Google Chat di cui l'utente è membro.

Quando vengono impostati sia includeVariables sia type, il campo di input combina le loro esperienze. Gli utenti possono selezionare una variabile del type corrispondente da un menu a discesa e visualizzare i suggerimenti di completamento automatico.

Figura 4: un utente esamina i suggerimenti di completamento automatico quando sceglie uno spazio.
Figura 5: un utente seleziona la variabile di output di un passaggio precedente dal menu a discesa ➕Variabili.

Seleziona una sola variabile di output con un menu extra

Puoi configurare un SelectionInput widget per consentire agli utenti di selezionare una singola variabile di output da un passaggio precedente utilizzando un menu extra.

Quando imposti SelectionInputType su OVERFLOW_MENU, il widget funge da selettore di variabili dedicato. A differenza dell'utilizzo di includeVariables con TextInput, che converte i valori delle variabili in stringhe, OVERFLOW_MENU conserva il tipo di dati originale della variabile selezionata.

Apps Script

const selectionInput = CardService.newSelectionInput()
  .setFieldName("variable_picker_1")
  .setTitle("Variable Picker")
  .setType(
    CardService.SelectionInputType.OVERFLOW_MENU
  );

Consenti agli utenti di combinare variabili di testo e di output

Puoi configurare TextInput widget per controllare il modo in cui gli utenti interagiscono con le variabili di testo e output utilizzando setInputMode().

RICH_TEXT: consente agli utenti di combinare variabili di testo e di output. Il risultato è una singola stringa concatenata.
PLAIN_TEXT: limita l'input. Gli utenti possono digitare testo o selezionare una singola variabile di output. La selezione di una variabile sostituisce qualsiasi testo esistente. Utilizza questa modalità per applicare tipi di dati specifici definiti nel file manifest.

L'immagine seguente mostra due widget TextInput. Il primo è configurato come RICH_TEXT e include testo e una variabile di output. Il secondo è configurato come PLAIN_TEXT e consente solo una variabile di output.

Figura 3: widget di input di testo configurati come RICH_TEXT e PLAIN_TEXT.

Ti consigliamo di impostare esplicitamente la modalità di input per tutti i widget TextInput.

Ecco il file manifest per la configurazione dei widget TextInput con diverse modalità di input:

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"
          }
        }
      ]
    }
  }
}

Ecco il codice per la configurazione dei widget TextInput con diverse modalità di input:

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) {
}

Personalizza i pulsanti del selettore di variabili

Puoi personalizzare il pulsante del selettore di variabili impostando le dimensioni e l'etichetta del pulsante.

Dimensioni pulsante

Per impostare le dimensioni del pulsante, utilizza setVariableButtonSize() con una delle seguenti enumerazioni VariableButtonSize:

UNSPECIFIED: il valore predefinito. Il pulsante è compatto nel riquadro laterale e a schermo intero in altri contesti.
COMPACT: il pulsante mostra solo un segno più (+).
FULL_SIZE: il pulsante mostra l'etichetta di testo completa.

Etichetta pulsante

Per impostare il testo del pulsante, utilizza setVariableButtonLabel().

Esempio: personalizzazione del selettore di variabili

L'esempio seguente mostra come configurare i widget TextInput con diverse dimensioni dei pulsanti del selettore di variabili e un'etichetta personalizzata.

Figura 1: personalizzazione del pulsante del selettore di variabili sul web.
Figura 2: personalizzazione del pulsante del selettore di variabili in un riquadro laterale del componente aggiuntivo.

Ecco il file manifest per la personalizzazione dei pulsanti del selettore di variabili:

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"
          }
        }
      ]
    }
  }
}

Ecco il codice per la personalizzazione dei pulsanti del selettore di variabili:

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) {
}

Configura il completamento automatico dei dati di Google Workspace

Puoi anche compilare i suggerimenti di completamento automatico dai dati dell'ambiente Google Workspace dell'utente:

Utenti di Google Workspace: compila gli utenti all'interno della stessa organizzazione Google Workspace.
Spazi di Google Chat: compila gli spazi di Google Chat di cui l'utente è membro.

Per configurare questa impostazione, imposta il PlatformDataSource nel widget SelectionInput, specificando il WorkflowDataSourceType come USER o 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)
            ))
    );

Esempio: combinazione di tipi di completamento automatico

L'esempio seguente mostra una funzione onConfig che crea una scheda con tre SelectionInput widget, che dimostrano il completamento automatico lato server, utente e spazio:

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();
}

Convalida la variabile di input

Come best practice, convalida che l'utente inserisca un valore appropriato. Consulta Convalida una variabile di input.

Raccogliere dati con una variabile di input Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Definisci la variabile di input nel file manifest

JSON

Definisci la variabile di input nel codice

Apps Script

Utilizza le variabili di output dei passaggi precedenti

Abilita la selezione delle variabili

Seleziona una sola variabile di output con un menu extra

Apps Script

Consenti agli utenti di combinare variabili di testo e di output

JSON

Apps Script

Personalizza i pulsanti del selettore di variabili

Dimensioni pulsante

Etichetta pulsante

Esempio: personalizzazione del selettore di variabili

JSON

Apps Script

Configura il completamento automatico dei dati di Google Workspace

Apps Script

Esempio: combinazione di tipi di completamento automatico

JSON

Apps Script

Convalida la variabile di input

Argomenti correlati

Raccogliere dati con una variabile di input