In questa pagina viene spiegato come aggiungere widget ed elementi UI a messaggi di schede o finestre di dialogo in modo che gli utenti possano interagire con l'app Google Chat, ad esempio facendo clic su un pulsante o inviando informazioni.
Utilizza Card Builder per progettare e visualizzare l'anteprima di 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 testo e un'icona. Ciascun Button supporta un'azione OnClick che si verifica quando gli utenti fanno clic sul pulsante. Ad esempio:
- Apri un link ipertestuale con
OpenLinkper fornire agli utenti ulteriori informazioni. - Esegui una
actionche esegua una funzione personalizzata, come la chiamata a un'API.
Per l'accessibilità, i pulsanti supportano il testo alternativo.
Aggiungi un pulsante che esegue una funzione personalizzata
Di seguito è riportata una scheda composta 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".
Aggiungi un pulsante con 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 composta da un widget ButtonList con due
pulsanti. Un pulsante utilizza il campo Color per personalizzare il colore di sfondo. L'altro pulsante viene disattivato con il campo Disabled, che impedisce all'utente di fare clic sul pulsante ed eseguire la funzione.
Aggiungi un pulsante con un'icona
Di seguito viene mostrata una scheda composta da un widget ButtonList con due widget Button a forma di icona. Un pulsante utilizza il campo knownIcon per visualizzare l'icona 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 visualizzata una scheda composta da un widget ButtonList che richiede
all'utente di inviare un'email. Il primo pulsante mostra un'icona
email e il secondo del testo. L'utente può fare clic sull'icona o sul pulsante di testo
per eseguire la funzione sendEmail.
Aggiungi elementi dell'interfaccia utente 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, usa invece il widget TextInput.
Il widget SelectionInput supporta i suggerimenti, che aiutano gli utenti a inserire dati
uniformi, e le 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 nei moduli, vedi Ricevere i dati dei moduli.
Questa sezione fornisce esempi di schede che utilizzano il widget SelectionInput.
Gli esempi utilizzano diversi tipi di input della 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 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 utilizza i 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 compilare i dati da origini dinamiche, ad esempio un'applicazione Google Workspace o un'origine dati esterna.
Origini dati di Google Workspace
Puoi completare gli elementi di un menu a selezione multipla dalle seguenti origini dati in Google Workspace:
- Utenti Google Workspace: puoi completare solo gli utenti della stessa organizzazione Google Workspace.
- Spazi di Chat: l'utente che inserisce gli elementi nel menu di selezione multipla può visualizzare e selezionare solo gli spazi a cui appartiene all'interno della sua organizzazione Google Workspace.
Per utilizzare le origini dati di Google Workspace, specifica il campo platformDataSource. A differenza degli altri tipi di input di selezione, gli oggetti SectionItem vengono omessi, perché questi elementi di selezione provengono dinamicamente da Google Workspace.
Il seguente codice mostra un menu a selezione multipla di utenti di Google Workspace.
Per inserire 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
degli spazi di Chat. Per compilare gli spazi, l'input di selezione specifica il campo hostAppDataSource. Il menu di selezione multipla imposta inoltre
defaultToCurrentSpace su true, in modo che lo spazio attuale venga selezionato
per impostazione 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 anche compilare gli elementi da un'origine dati di terze parti o esterna. Ad esempio, puoi utilizzare 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, utilizza il campo externalDataSource per
specificare una funzione che restituisca elementi dall'origine dati.
Per ridurre le richieste a un'origine dati esterna, puoi includere elementi suggeriti che vengono visualizzati nel menu a selezione multipla prima che gli utenti ne digitino. 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 codice seguente mostra un menu a selezione multipla di voci da un insieme esterno di contatti per l'utente. Per impostazione predefinita, il menu visualizza un contatto ed esegue la funzione getContacts per recuperare e compilare 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 popola città degli Stati Uniti, la tua
app Chat può suggerire 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 sull'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 rappresenta l'interazione dell'utente con il menu.
- Identifica che il valore
invokedFunctiondell'evento di interazione corrisponda alla funzione del campoexternalDataSource. - Quando le funzioni corrispondono, restituisce gli elementi suggeriti dall'origine dati esterna. Per suggerire elementi in base a ciò che l'utente digita, ottieni il valore della chiave
autocomplete_widget_query. Questo valore rappresenta il testo digitato dall'utente nel menu.
Il seguente codice completa automaticamente gli elementi da una risorsa di dati esterna. Utilizzando
l'esempio precedente, l'app Chat suggerisce gli elementi in base
a quando viene attivata la funzione getContacts:
Apps Script
Node.js
Aggiungi un campo in cui un utente può inserire testo
Il widget TextInput
fornisce un campo in cui gli utenti possono inserire testo. Il widget supporta i suggerimenti, che aiutano gli utenti a inserire dati uniformi, e le azioni in caso di modifica, Actions che vengono eseguite quando viene apportata una modifica nel campo di immissione testo, ad esempio quando un utente aggiunge o elimina testo.
Quando devi raccogliere dati astratti o sconosciuti degli 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 i dati dei moduli.
Di seguito è riportata una scheda composta da un widget TextInput:
Consenti a un utente di scegliere una data e un'ora
Il widget DateTimePicker consente agli utenti di inserire una data, un'ora o entrambe le date e un'ora. 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 di inserire
le informazioni correttamente.
Per elaborare i valori di data e ora inseriti dagli utenti, vedi Ricevere i dati dei moduli.
Di seguito viene mostrata una scheda composta da tre diversi tipi di
widget DateTimePicker:
Convalida i dati inseriti nelle schede
In questa pagina viene spiegato come convalidare i dati inseriti nelle action
e nei widget di una scheda.
Ad esempio, puoi verificare che un campo di immissione di testo contenga testo inserito
dall'utente o che contenga un determinato numero di caratteri.
Imposta i widget necessari per le azioni
Come parte dell'elemento action della scheda,
aggiungi i nomi dei widget necessari a un'azione all'elenco requiredWidgets.
Se i widget elencati qui non hanno un valore quando viene richiamata questa azione, l'invio dell'azione del modulo viene annullato.
Quando è impostata un'azione su "all_widgets_are_required": "true", tutti i widget nella scheda sono richiesti per questa azione.
Imposta un'azione all_widgets_are_required in 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 in dateTimeSelettore
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
}
]
}
}
]
}
]
}
Impostare la convalida per un widget di input di testo
Nel campo di convalida del widget textInput, è possibile specificare il limite di caratteri e il tipo di immissione per questo widget di inserimento 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
}
}
}
]
}
]
}
Impostare 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, l'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la richiesta". A volte nella UI di Chat non viene visualizzato alcun messaggio di errore, ma l'app o la scheda Chat produce un risultato imprevisto. Ad esempio, il messaggio di una 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 informazioni su visualizzazione, debug e correzione degli errori, vedi Risolvere i problemi e correggere gli errori di Google Chat.