Questa guida spiega come creare una scheda di configurazione che consenta agli utenti di personalizzare e fornire input per un passaggio in Google Workspace Studio.
In generale, per creare una scheda di configurazione, devi creare un'interfaccia della scheda come faresti per qualsiasi altro componente aggiuntivo di Google Workspace. Per assistenza nella creazione di interfacce di schede di configurazione, consulta quanto segue:
- Il generatore di schede, uno strumento interattivo che ti aiuta a creare e definire le schede.
- Scheda nella documentazione di riferimento dell'API Google Workspace Add-ons.
- Servizio schede, un servizio Apps Script che consente agli script di configurare e creare schede.
- Interfacce basate su schede nella documentazione per gli sviluppatori di componenti aggiuntivi di Google Workspace.
Alcuni widget delle schede hanno funzionalità e caratteristiche speciali specifiche di Workspace Studio, descritte in dettaglio in questa guida.
Definire una scheda di configurazione
Definisci una scheda di configurazione sia nel manifest di Apps Script sia nel codice.
L'esempio seguente mostra come creare una scheda di configurazione che chiede agli utenti di selezionare uno spazio Google Chat.
Modificare il file manifest
Nel file manifest, definisci workflowElements.
JSON
{
"timeZone": "America/Los_Angeles",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Chat space selector",
"logoUrl": "https://www.gstatic.com/images/branding/productlogos/gsuite_addons/v6/web-24dp/logo_gsuite_addons_color_1x_web_24dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "actionElement",
"state": "ACTIVE",
"name": "Chat space selector",
"description": "Lets the user select a space from Google Chat",
"workflowAction": {
"inputs": [
{
"id": "chooseSpace",
"description": "Choose a Chat space",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"onConfigFunction": "onConfigSpacePicker",
"onExecuteFunction": "onExecuteSpacePicker"
}
}
]
}
}
}
Modifica il codice
Nel codice dell'applicazione, restituisci una scheda.
Apps Script
/**
* Generates and displays a configuration card to choose a Chat space
*/
function onConfigSpacePicker() {
const selectionInput = CardService.newSelectionInput()
.setTitle("First Value")
.setFieldName("chooseSpace")
.setType(CardService.SelectionInputType.MULTI_SELECT)
.setPlatformDataSource(
CardService.newPlatformDataSource()
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setType(CardService.WorkflowDataSourceType.SPACE)
)
)
);
const cardSection = CardService.newCardSection()
.setHeader("Select Chat Space")
.setId("section_1")
.addWidget(selectionInput)
var card = CardService.newCardBuilder()
.addSection(cardSection)
.build();
return card;
}
function onExecuteSpacePicker(e) {
}
Configurare il completamento automatico per i widget di input
Puoi configurare il completamento automatico per i widget
SelectionInput per aiutare gli utenti a scegliere da un elenco di opzioni. Ad esempio, se un utente inizia a digitare Atl per un menu che popola le città degli Stati Uniti, l'elemento può suggerire automaticamente Atlanta prima che l'utente finisca di digitare. Puoi completare automaticamente fino a 100 elementi.
I suggerimenti di completamento automatico possono provenire dalle seguenti origini dati:
- Completamento automatico lato server:i suggerimenti vengono compilati da un'origine dati di terze parti o esterna che definisci.
- Dati di Google Workspace:i suggerimenti vengono compilati a partire da fonti di Google Workspace, come utenti di Google Workspace o spazi di Google Chat.
Completamento automatico lato server
Puoi configurare un widget
SelectionInput per completare automaticamente i suggerimenti da un'origine dati
esterna. Ad esempio, puoi aiutare gli utenti a selezionare un elenco di lead di vendita da un sistema di gestione dei rapporti con i clienti (CRM).
Per implementare il completamento automatico lato server, devi:
- Definisci l'origine dati:nel widget
SelectionInput, aggiungi unDataSourceConfigche specifica unRemoteDataSource. Questa configurazione punta a una funzione Apps Script che recupera i suggerimenti di completamento automatico. - Implementa la funzione di completamento automatico:questa funzione viene attivata quando l'utente digita nel campo di input. La funzione deve eseguire query sulla sorgente di dati esterni in base all'input dell'utente e restituire un elenco di suggerimenti.
L'esempio seguente mostra come configurare un widget
SelectionInput
per il completamento automatico lato server:
Apps Script
// In your onConfig function:
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)
))
)
);
// ... add widget to card ...
Gestire la richiesta di completamento automatico
La funzione specificata in
setFunctionName (ad es. getAutocompleteResults) riceve un
oggetto evento quando l'utente digita nel campo. Questa funzione deve:
- Controlla
event.workflow.elementUiAutocomplete.invokedFunctionper assicurarti che corrisponda al nome della funzione previsto. - Recupera l'input dell'utente da
event.workflow.elementUiAutocomplete.query. - Esegui una query sull'origine dati esterna utilizzando la query.
- Restituisci fino a 100 suggerimenti nel formato richiesto.
L'esempio seguente mostra come implementare la funzione handleAutocompleteRequest() per restituire suggerimenti in base alla query dell'utente:
Apps Script
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 based on the query
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();
}
// In your onConfig function, handle the autocomplete event
function onConfigAutocompleteTest(event) {
// Handle autocomplete request
if (event.workflow && event.workflow.elementUiAutocomplete) {
return handleAutocompleteRequest(event);
}
// ... rest of your card building logic ...
}
Completamento automatico dei dati di Google Workspace
Puoi anche compilare i suggerimenti di completamento automatico con i dati dell'ambiente Google Workspace dell'utente:
- Utenti di Google Workspace:popola 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
PlatformDataSource
nel widget
SelectionInput, specificando
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 widget SelectionInput, che dimostra 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();
}
Personalizzare i pulsanti del selettore di variabili
Puoi personalizzare il pulsante del selettore di variabili impostando le dimensioni e l'etichetta.
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 grandezza naturale 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 del pulsante di selezione delle variabili e un'etichetta personalizzata.
-
Figura 1: personalizzazione del pulsante del selettore di variabili sul web. -
Figura 2: personalizzazione del pulsante di selezione delle variabili in un riquadro laterale del componente aggiuntivo.
Ecco il file manifest per personalizzare i pulsanti del selettore delle 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 personalizzare i 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) {
}
Funzionalità specifiche di Workspace Studio
Alcuni widget delle schede hanno funzionalità specifiche di Workspace Studio, descritte qui.
TextInput e SelectionInput
I widget TextInput e SelectionInput hanno queste funzionalità specifiche di Workspace Studio:
includeVariables: una proprietà booleana che consente agli utenti di selezionare le variabili dai 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 sono impostati sia includeVariables sia type, il campo di input combina le loro
esperienze. Gli utenti possono selezionare una variabile della corrispondenza type da un menu a discesa
e visualizzare i suggerimenti di completamento automatico.
-
Figura 3: un utente esamina i suggerimenti di completamento automatico quando sceglie uno spazio. -
Figura 4: 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 widget SelectionInput
per consentire agli utenti di selezionare una singola variabile di output
da un passaggio precedente utilizzando un menu di overflow.
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
);
Consentire agli utenti di combinare variabili di testo e di output
Puoi configurare i widget TextInput per controllare il modo in cui gli utenti interagiscono con il testo e le variabili di output utilizzando setInputMode().
RICH_TEXT: consente agli utenti di combinare testo e variabili di output. Il risultato è una singola stringa concatenata.PLAIN_TEXT: limita l'input. Gli utenti possono digitare un 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 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 5: widget di input di testo configurati come RICH_TEXTePLAIN_TEXT.
Ti consigliamo di impostare esplicitamente la modalità di inserimento 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 configurare i 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) {
}
Considerazioni e limitazioni relative alla carta
La navigazione a schede, ad esempio
popCard(),pushCard()eupdateCard()non è supportata nei componenti aggiuntivi che estendono Workspace Studio.Quando
SelectionInputviene utilizzato in un selettore di variabili, i widget supportano solo"type": "MULTI_SELECT". In altre schede di configurazione,SelectionInputsupporta tutti i valori diSelectionType.
Argomenti correlati
- Creare un passaggio
- Variabili di input
- Convalidare una variabile di input
- Variabili di output
- Registrare attività ed errori
- Oggetti evento di Workspace Studio