In questa pagina viene spiegato come aggiungere widget ed elementi dell'interfaccia utente a messaggi di schede o finestre di dialogo in modo che gli utenti possano interagire con la tua app Google Chat, ad esempio facendo clic su un pulsante o inviando informazioni.
Utilizza Card Builder per progettare e visualizzare l'anteprima dei messaggi delle schede JSON per le app di chat:
Apri Card BuilderPrerequisiti
Aggiungi un pulsante
Il widget ButtonList
mostra una serie di pulsanti. I pulsanti possono mostrare testo,
un'icona o sia testo che un'icona. Ogni elemento Button
supporta un'azione OnClick
che si verifica quando gli utenti fanno clic sul pulsante. Ad esempio:
- Apri un link ipertestuale con
OpenLink
per fornire agli utenti informazioni aggiuntive. - Esegui un'istanza
action
che esegue una funzione personalizzata, ad esempio una chiamata a un'API.
Per l'accessibilità, i pulsanti supportano testo alternativo.
Aggiungi un pulsante che esegue una funzione personalizzata
Quella che segue è una scheda costituita da un widget ButtonList
con due pulsanti.
Un pulsante apre la documentazione per gli sviluppatori di Google Chat in una nuova scheda. L'altro pulsante esegue una funzione personalizzata denominata goToView()
e passa il parametro viewType="BIRD EYE VIEW"
.
Aggiungere un pulsante con un colore personalizzato e un pulsante disattivato
Puoi impedire agli utenti di fare clic su un pulsante impostando "disabled": "true"
.
Di seguito viene mostrata una scheda costituita da un widget ButtonList
con due
pulsanti. Un pulsante utilizza il campo Color
per personalizzare il colore di sfondo del pulsante. L'altro pulsante viene disattivato con il campo Disabled
, che impedisce all'utente di fare clic sul pulsante ed eseguire la funzione.
Aggiungere un pulsante con un'icona
Di seguito viene mostrata una scheda costituita da un widget ButtonList
con due widget icona Button
. Un pulsante utilizza il campo knownIcon
per visualizzare l'icona dell'email integrata di Google Chat. L'altro pulsante utilizza il campo iconUrl
per visualizzare un widget icona personalizzata.
Aggiungi un pulsante con un'icona e del testo
Di seguito viene mostrata una scheda costituita da un widget ButtonList
che richiede all'utente di inviare un'email. Il primo pulsante mostra un'icona di email, mentre il secondo mostra del testo. L'utente può fare clic sull'icona o sul pulsante di testo
per eseguire la funzione sendEmail
.
Aggiungi elementi UI selezionabili
Il widget SelectionInput
fornisce un insieme di elementi selezionabili, come caselle di controllo, pulsanti di opzione, opzioni o un menu a discesa. Puoi usare questo widget
per raccogliere dati definiti e standardizzati dagli utenti. Per raccogliere dati non definiti dagli utenti, utilizza invece il widget TextInput
.
Il widget SelectionInput
supporta i suggerimenti, che aiutano gli utenti a inserire dati
uniformi, e azioni in caso di modifica, ovvero
Actions
che vengono eseguite quando si verifica una modifica in un campo di immissione di selezione, ad esempio un utente
che seleziona o deseleziona un elemento.
Le app di chat possono ricevere ed elaborare il valore degli elementi selezionati. Per maggiori dettagli sull'utilizzo degli input dei moduli, consulta Ricevere dati dei moduli.
Questa sezione fornisce esempi di schede che utilizzano il widget SelectionInput
.
Gli esempi utilizzano diversi tipi di input di sezione:
Aggiungi una casella di controllo
Di seguito viene visualizzata una finestra di dialogo che chiede all'utente di specificare se un contatto è professionale, personale o entrambi, con un widget SelectionInput
che utilizza le caselle di controllo:
Aggiungi un pulsante di opzione
Di seguito viene visualizzata una finestra di dialogo che chiede all'utente di specificare se un contatto è professionale o personale con un widget SelectionInput
che usa pulsanti di opzione:
Aggiungi un sensore
Di seguito viene visualizzata una finestra di dialogo che chiede all'utente di specificare se un contatto è professionale, personale o entrambi con un widget SelectionInput
che utilizza sensori:
Aggiungi un menu a discesa
Di seguito viene visualizzata una finestra di dialogo che chiede all'utente di specificare se un contatto è professionale o personale con un widget SelectionInput
che utilizza un menu a discesa:
Aggiungi un menu a selezione multipla
Di seguito viene visualizzata una finestra di dialogo che chiede all'utente di selezionare i contatti da un menu a selezione multipla:
Utilizzare le origini dati per i menu a selezione multipla
La sezione seguente spiega come utilizzare i menu a selezione multipla per completare i dati dalle origini dinamiche, come un'applicazione Google Workspace o un'origine dati esterna.
Origini dati di Google Workspace
Puoi completare gli elementi per un menu a selezione multipla dalle seguenti origini dati in Google Workspace:
- Utenti Google Workspace: puoi inserire solo gli utenti appartenenti alla stessa organizzazione Google Workspace.
- Spazi di Chat: l'utente che inserisce le voci nel menu di selezione multipla può solo visualizzare e selezionare gli spazi a cui appartiene all'interno della propria organizzazione Google Workspace.
Per utilizzare le origini dati Google Workspace, devi specificare il campo platformDataSource
. A differenza degli altri tipi di input di selezione, gli oggetti SectionItem
vengono omessi, poiché questi elementi di selezione vengono recuperati dinamicamente da Google Workspace.
Il seguente codice mostra un menu a selezione multipla di utenti di Google Workspace.
Per compilare gli utenti, l'input di selezione imposta commonDataSource
su USER
:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"commonDataSource": "USER"
}
}
}
Il seguente codice mostra un menu a selezione multipla di spazi di Chat. Per compilare gli spazi, l'input di selezione specifica il campo hostAppDataSource
. Il menu di selezione multipla imposta anche
defaultToCurrentSpace
su true
, il che rende lo spazio corrente la selezione
predefinita nel menu:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
Origini dati esterne a Google Workspace
I menu a selezione multipla possono completare gli elementi anche da un'origine dati di terze parti o esterna. Ad esempio, puoi utilizzare i menu a selezione multipla per aiutare un utente a effettuare una selezione da un elenco di lead di vendita da un sistema di gestione dei rapporti con i clienti (CRM).
Per utilizzare un'origine dati esterna, usa il campo externalDataSource
per specificare una funzione che restituisca elementi dall'origine dati.
Per ridurre le richieste a un'origine dati esterna, puoi includere gli elementi suggeriti che vengono visualizzati nel menu di selezione multipla prima che gli utenti digitino il menu. Ad esempio, puoi inserire i contatti cercati di recente per l'utente. Per completare gli elementi suggeriti da un'origine dati esterna, specifica gli oggetti SelectionItem
.
Il seguente codice mostra un menu a selezione multipla di elementi da un
insieme di contatti esterno per l'utente. Il menu visualizza un contatto per impostazione predefinita ed esegue la funzione getContacts
per recuperare e completare gli elementi dall'origine dati esterna:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 2,
"externalDataSource": {
"function": "getContacts"
},
"items": [
{
"text": "Contact 3",
"value": "contact-3",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"bottomText": "Contact three description",
"selected": false
}
]
}
}
Per le origini dati esterne, puoi anche completare automaticamente gli elementi che gli utenti iniziano a digitare nel menu di selezione multipla. Ad esempio, se un utente inizia a digitare Atl
per un
menu che compila le città negli Stati Uniti, l'app Chat può suggerirti automaticamente Atlanta
prima che l'utente
finisca di digitare. Puoi completare automaticamente fino a 100 elementi.
Per completare automaticamente gli elementi, crei una funzione che esegue una query nell'origine dati esterna e restituisce gli elementi ogni volta che un utente digita nel menu di selezione multipla. La funzione deve:
- Trasmetti un oggetto evento che rappresenti l'interazione dell'utente con il menu.
- Verifica che il valore
invokedFunction
dell'evento di interazione corrisponda alla funzione del campoexternalDataSource
. - Quando le funzioni corrispondono, restituisci gli elementi suggeriti dall'origine dati esterna. Per suggerire elementi in base a ciò che l'utente digita, ottieni il valore per la chiave
autocomplete_widget_query
. Questo valore rappresenta ciò che l'utente digita nel menu.
Il codice seguente completa automaticamente gli elementi da una risorsa dati esterna. Utilizzando l'esempio precedente, l'app di Chat suggerisce elementi in base a quando viene attivata la funzione getContacts
:
Apps Script
Node.js
Aggiungi un campo in cui l'utente può inserire del testo
Il widget TextInput
fornisce un campo in cui gli utenti possono inserire del testo. Il widget supporta suggerimenti che aiutano gli utenti a inserire dati uniformi e azioni in caso di modifica, che vengonoActions
eseguite quando si verifica una modifica nel campo di immissione testo, ad esempio un utente che aggiunge o elimina testo.
Quando devi raccogliere dati astratti o sconosciuti dagli utenti, utilizza questo widget TextInput
. Per raccogliere dati definiti dagli utenti, utilizza invece il widget SelectionInput
.
Per elaborare il testo inserito dagli utenti, vedi Ricevere dati dei moduli.
Di seguito è riportata una scheda costituita da un widget TextInput
:
Consentire a un utente di scegliere una data e un'ora
Il widget DateTimePicker
consente agli utenti di inserire una data, un'ora o entrambe. In alternativa, gli utenti possono utilizzare il selettore per selezionare date e orari. Se gli utenti inseriscono
una data o un'ora non valide, il selettore mostra un errore che richiede agli utenti di inserire
le informazioni correttamente.
Per elaborare i valori di data e ora inseriti dagli utenti, vedi Ricevere dati dei moduli.
Di seguito viene mostrata una scheda costituita da tre diversi tipi di
widget DateTimePicker
:
Convalida i dati inseriti nelle schede
Questa pagina spiega come convalidare i dati inseriti nei widget action
e nei widget di una scheda.
Ad esempio, puoi verificare che un campo di immissione testo contenga del testo inserito dall'utente o che contenga un determinato numero di caratteri.
Imposta i widget richiesti per le azioni
Nell'ambito della sezione action
della scheda,
aggiungi i nomi dei widget necessari per l'azione al relativo elenco requiredWidgets
.
Se per i widget elencati qui non è presente un valore quando viene richiamata questa azione, l'invio dell'azione del modulo viene annullato.
Se "all_widgets_are_required": "true"
è impostata per un'azione, tutti i widget nella scheda
sono richiesti per questa azione.
Imposta un'azione all_widgets_are_required
nella selezione multipla
JSON
{
"sections": [
{
"header": "Select contacts",
"widgets": [
{
"selectionInput": {
"type": "MULTI_SELECT",
"label": "Selected contacts",
"name": "contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"onChangeAction": {
"all_widgets_are_required": true
},
"items": [
{
"value": "contact-1",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 1",
"bottomText": "Contact one description",
"selected": false
},
{
"value": "contact-2",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 2",
"bottomText": "Contact two description",
"selected": false
},
{
"value": "contact-3",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 3",
"bottomText": "Contact three description",
"selected": false
},
{
"value": "contact-4",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 4",
"bottomText": "Contact four description",
"selected": false
},
{
"value": "contact-5",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 5",
"bottomText": "Contact five description",
"selected": false
}
]
}
}
]
}
]
}
Imposta un'azione all_widgets_are_required
nel selettore della data/ora
JSON
{
"sections": [
{
"widgets": [
{
"textParagraph": {
"text": "A datetime picker widget with both date and time:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_date_and_time",
"label": "meeting",
"type": "DATE_AND_TIME"
}
},
{
"textParagraph": {
"text": "A datetime picker widget with just date:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_date_only",
"label": "Choose a date",
"type": "DATE_ONLY",
"onChangeAction":{
"all_widgets_are_required": true
}
}
},
{
"textParagraph": {
"text": "A datetime picker widget with just time:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_time_only",
"label": "Select a time",
"type": "TIME_ONLY"
}
}
]
}
]
}
Imposta un'azione all_widgets_are_required
nel menu a discesa
JSON
{
"sections": [
{
"header": "Section Header",
"collapsible": true,
"uncollapsibleWidgetsCount": 1,
"widgets": [
{
"selectionInput": {
"name": "location",
"label": "Select Color",
"type": "DROPDOWN",
"onChangeAction": {
"all_widgets_are_required": true
},
"items": [
{
"text": "Red",
"value": "red",
"selected": false
},
{
"text": "Green",
"value": "green",
"selected": false
},
{
"text": "White",
"value": "white",
"selected": false
},
{
"text": "Blue",
"value": "blue",
"selected": false
},
{
"text": "Black",
"value": "black",
"selected": false
}
]
}
}
]
}
]
}
Imposta la convalida per un widget di input di testo
Nel campo di convalida del widget textInput
può specificare il limite di caratteri e il tipo di input per questo widget di immissione testo.
Imposta un limite di caratteri per un widget di input di testo
JSON
{
"sections": [
{
"header": "Tell us about yourself",
"collapsible": true,
"uncollapsibleWidgetsCount": 2,
"widgets": [
{
"textInput": {
"name": "favoriteColor",
"label": "Favorite color",
"type": "SINGLE_LINE",
"validation": {"character_limit":15},
"onChangeAction":{
"all_widgets_are_required": true
}
}
}
]
}
]
}
Imposta il tipo di input per un widget di input di testo
JSON
{
"sections": [
{
"header": "Validate text inputs by input types",
"collapsible": true,
"uncollapsibleWidgetsCount": 2,
"widgets": [
{
"textInput": {
"name": "mailing_address",
"label": "Please enter a valid email address",
"type": "SINGLE_LINE",
"validation": {
"input_type": "EMAIL"
},
"onChangeAction": {
"all_widgets_are_required": true
}
}
},
{
"textInput": {
"name": "validate_integer",
"label": "Please enter a number",
"type": "SINGLE_LINE",
"validation": {
"input_type": "INTEGER"
}
}
},
{
"textInput": {
"name": "validate_float",
"label": "Please enter a number with a decimal",
"type": "SINGLE_LINE",
"validation": {
"input_type": "FLOAT"
}
}
}
]
}
]
}
Risolvi il problema
Quando un'app o una scheda Google Chat restituisce un errore, nell'interfaccia di Chat viene visualizzato il messaggio "Si è verificato un problema". o "Impossibile elaborare la richiesta". A volte nella UI di Chat non vengono visualizzati messaggi di errore, ma l'app o la scheda di Chat produce un risultato imprevisto; ad esempio, un messaggio di scheda potrebbe non essere visualizzato.
Anche se un messaggio di errore potrebbe non essere visualizzato nell'interfaccia utente di Chat, sono disponibili messaggi di errore descrittivi e dati di log per aiutarti a correggere gli errori quando il logging degli errori per le app di Chat è attivato. Per assistenza su visualizzazione, debug e correzione degli errori, consulta l'articolo Risolvere gli errori di Google Chat.