In questa pagina viene spiegato come aggiungere widget ed elementi UI a messaggi delle schede o delle finestre di dialogo per consentire agli utenti di interagire con la tua app Google Chat, ad esempio fare clic su un pulsante o inviare informazioni.
Utilizza Card Builder per progettare e visualizzare l'anteprima di messaggi delle schede JSON per le app di chat:
Apri il generatore di schedePrerequisiti
Aggiungi un pulsante
La
Widget ButtonList
mostra una serie di pulsanti. I pulsanti possono visualizzare testo,
di testo e un'icona. Ciascuna
Button
supporta
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
actionche esegue una funzione personalizzata, ad esempio 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. La
Questo pulsante esegue una funzione personalizzata denominata goToView() e trasmette
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
Campo Color
per personalizzare lo sfondo del pulsante
colore. 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 icone
Widget Button. Un pulsante utilizza
knownIcon
per visualizzare l'icona email integrata di Google Chat. L'altro pulsante utilizza
campo iconUrl per visualizzare
widget icona personalizzata.
Aggiungi un pulsante con un'icona e del testo
Di seguito viene mostrata una scheda composta da un widget ButtonList che richiede
all'utente di inviare un'email. Il primo pulsante mostra un'icona di email e
secondo pulsante con testo. L'utente può fare clic sull'icona o sul testo
per eseguire la funzione sendEmail.
Aggiungi elementi dell'interfaccia utente selezionabili
Il widget SelectionInput
fornisce una serie 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. Raccogliere dati non definiti
dagli utenti, usa invece il widget TextInput.
Il widget SelectionInput supporta i suggerimenti, che aiutano gli utenti a entrare in modo uniforme
e azioni in caso di modifica, che sono
Actions
che vengono eseguite quando si verifica una modifica in un campo di immissione di selezione, come
selezionando o deselezionando un elemento.
Le app di chat possono ricevere ed elaborare il valore degli elementi selezionati. Per maggiori dettagli sull'utilizzo degli input modulo, vedi Elabora le informazioni inserite dagli utenti.
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
il 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 personale o professionale con un widget di 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
il contatto è professionale, personale o entrambi con un widget SelectionInput che
utilizza interruttori:
Aggiungi un menu a discesa
Di seguito viene visualizzata una finestra di dialogo che chiede all'utente di specificare se un
contatto personale o professionale con un widget di SelectionInput che usa
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 scelta 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, come un'applicazione Google Workspace o dati esterni sorgente.
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 all'interno degli della stessa organizzazione Google Workspace.
- Spazi di Chat: l'utente che inserisce gli elementi nella selezione multipla può solo visualizzare e selezionare gli spazi a cui appartengono dell'organizzazione Google Workspace.
Per utilizzare le origini dati di Google Workspace, devi specificare
platformDataSource
. A differenza degli altri tipi di input di selezione,
SectionItem
poiché 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 di Chat
spazi di archiviazione. Per compilare gli spazi, l'input di selezione specifica
campo hostAppDataSource. Il menu a selezione multipla imposta anche
Da defaultToCurrentSpace a true, in questo modo lo spazio corrente diventa predefinito
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 elementi da dati di terze parti o esterni sorgente. Ad esempio, puoi utilizzare i menu a selezione multipla per aiutare un utente a selezionare da una un elenco di potenziali acquirenti di 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 restituisce gli elementi dall'origine dati.
Per ridurre le richieste a un'origine dati esterna, puoi includere
elementi suggeriti che appaiono nel menu a selezione multipla prima che gli utenti digitino
il menu. Ad esempio, puoi completare i contatti cercati di recente per
utente. Per compilare gli elementi suggeriti da un'origine dati esterna, specifica
SelectionItem
di oggetti strutturati.
Il seguente codice mostra un menu a selezione multipla di elementi da un
insieme di contatti esterni dell'utente. Nel menu viene visualizzato un contatto per impostazione predefinita
ed esegue la funzione getContacts per recuperare e compilare gli elementi dalla
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 avviati dagli utenti
digitando nel menu di selezione multipla. Ad esempio, se un utente inizia a digitare Atl per una
che popola le città degli Stati Uniti, i tuoi
L'app di chat può suggerire automaticamente Atlanta prima che l'utente
termina di digitare. Puoi completare automaticamente fino a 100 elementi.
Per completare automaticamente gli elementi, crei una funzione che esegue query sui dati esterni source e restituisce gli elementi ogni volta che un utente digita nel menu di selezione multipla. La deve eseguire le seguenti operazioni:
- Trasmetti un oggetto evento che rappresenta l'interazione dell'utente con il menu.
- Verifica che l'evento di interazione
invokedFunctioncorrisponde alla funzione del campoexternalDataSource. - Quando le funzioni corrispondono, restituiscono gli elementi suggeriti dai dati esterni
sorgente. Per suggerire elementi in base a ciò che l'utente digita, ottieni il valore per
autocomplete_widget_querychiave. Questo valore rappresenta ciò che l'utente digita nel menu.
Il seguente codice completa automaticamente gli elementi da una risorsa di dati esterna. L'utilizzo del
nell'esempio precedente, l'app Chat suggerisce elementi basati
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. La
supporta i suggerimenti, che aiutano gli utenti a inserire dati uniformi e quando
azioni, che sono
Actions
che vengono eseguite quando si verifica una modifica nel campo di immissione testo, come un utente che aggiunge o
l'eliminazione di testo.
Quando devi raccogliere dati astratti o sconosciuti degli utenti, utilizza questo
Widget TextInput. Per raccogliere dati definiti dagli utenti, utilizza la
SelectionInput
widget.
Per elaborare il testo inserito dagli utenti, consulta Elabora le informazioni inserite dagli utenti.
Di seguito è riportata una scheda composta da un widget TextInput:
Consenti a un utente di scegliere una data e un'ora
La
Widget DateTimePicker
consente agli utenti di inserire una data, un'ora o entrambi
una volta. In alternativa, gli utenti possono utilizzare il selettore per selezionare date e orari. Se gli utenti inseriscono
data o ora non valide, il selettore mostra un errore che chiede agli utenti di inserire
le informazioni in modo corretto.
Per elaborare i valori di data e ora inseriti dagli utenti, consulta Elabora le informazioni inserite dagli utenti.
Di seguito viene mostrata una scheda composta da tre diversi tipi di
DateTimePicker widget:
Convalida i dati inseriti nelle schede
Questa pagina spiega come convalidare i dati inseriti nel action di una scheda
e widget.
Ad esempio, puoi verificare che un campo di immissione di testo contenga testo inserito dal
utente o che contenga un certo numero di caratteri.
Imposta i widget necessari per le azioni
Nell'ambito della action della carta,
aggiunge 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 "all_widgets_are_required": "true" è impostata per compiere un'azione, vengono usati 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
In textInput
campo di convalida del widget, può specificare il limite di caratteri e il tipo di input per
questo widget per l'inserimento di 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"
}
}
}
]
}
]
}
Risoluzione dei problemi
Quando un'app Google Chat o card restituisce un errore, L'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la richiesta". A volte, l'UI di Chat non mostra alcun messaggio di errore, ma l'app Chat o la scheda restituisce un risultato inaspettato; Ad esempio, il messaggio di una scheda potrebbe non vengono visualizzate.
Anche se un messaggio di errore potrebbe non essere visualizzato nella UI di Chat, messaggi di errore descrittivi e dati di log che ti aiuteranno a correggere gli errori quando il logging degli errori per le app di chat è attivo. Per assistenza con la visualizzazione, il debug e la correzione degli errori, consulta Risolvere i problemi e correggere gli errori di Google Chat.