Aggiungere elementi interattivi dell'interfaccia utente alle schede

In questa pagina viene spiegato come aggiungere widget ed elementi UI alle schede. per consentire agli utenti di interagire con la tua app Google Chat, ad esempio fare clic su un pulsante o inviare informazioni.

Le app di chat possono utilizzare le seguenti interfacce di Chat per creare schede interattive:

  • Messaggi che contengono una o più schede.
  • Home page che viene visualizzata dalla scheda Home nella visualizzazione i messaggi con l'app Chat.
  • Finestre di dialogo, ovvero schede che si aprono in una nuova finestra dai messaggi e dalle home page.

Quando gli utenti interagiscono con le schede, le app di chat possono utilizzare i dati ricevuto per elaborare e rispondere di conseguenza. Per maggiori dettagli, vedi Raccogliere ed elaborare informazioni dagli utenti di Google Chat.


Utilizza Card Builder per progettare e visualizzare l'anteprima dei messaggi e delle interfacce utente delle app di chat:

Apri il generatore di schede

Prerequisiti

Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un interattiva di Chat, completa una delle seguenti guide rapide basate nell'architettura dell'app che vuoi utilizzare:

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 action che 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".

Aggiungere un pulsante con lo stile Material Design

Di seguito viene mostrata una serie di pulsanti in un pulsante Material Design diverso stili.

Per applicare lo stile Material Design, non includere il valore "colore" .

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.

Personalizza il pulsante per una sezione comprimibile

Personalizza il pulsante di controllo che comprime ed espande le sezioni all'interno di un . Scegli tra una serie di icone o immagini che rappresentano visivamente il contenuti della sezione, semplificando la comprensione e l'interazione da parte degli utenti le informazioni.

Aggiungi un menu extra

La Overflow menu possono essere utilizzate nelle schede Chat per offrire ulteriori opzioni e azioni. Consente di includi altre opzioni senza ingombrare l'interfaccia della scheda, assicurandoti un design pulito e organizzato.

Aggiungi un elenco di chip

La ChipList fornisce un modo versatile e visivamente accattivante per visualizzare le informazioni. Utilizza gli elenchi di chip per rappresentare tag, categorie o altri dati pertinenti, in modo che la navigazione e l'interazione con i tuoi contenuti.

Raccogliere informazioni dagli utenti

Questa sezione spiega come aggiungere widget che raccolgono informazioni, ad esempio: testo o selezioni.

Per scoprire come elaborare gli input degli utenti, consulta Raccogliere ed elaborare informazioni dagli utenti di Google Chat.

Raccogliere testo

Il widget TextInput fornisce un campo in cui gli utenti possono inserire testo. La il widget 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.

Di seguito è riportata una scheda composta da un widget TextInput:

Raccogli date o orari

La Widget DateTimePicker consente agli utenti di inserire una data, un'ora o sia una data 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.

Di seguito viene mostrata una scheda composta da tre diversi tipi di DateTimePicker widget:

Consenti agli utenti di selezionare elementi

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 scheda che chiede all'utente di specificare se: 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 scheda che chiede all'utente di specificare se: contatto personale o professionale con un widget di SelectionInput che usa pulsanti di opzione:

Aggiungi un sensore

Di seguito viene visualizzata una scheda che chiede all'utente di specificare se: il contatto è professionale, personale o entrambi con un widget SelectionInput che utilizza interruttori:

Di seguito viene visualizzata una scheda che chiede all'utente di specificare se: 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 scheda che chiede all'utente di selezionare i contatti da un menu a scelta multipla:

Puoi completare gli elementi di un menu a selezione multipla dai seguenti 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
          }
        }
      }
    }
  }
}

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 invokedFunction corrisponde alla funzione del campo externalDataSource.
  • 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_query chiave. 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

apps-script/selection-input/on-widget-update.gs
/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          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
            },
          ]
        }
      }
    }
  };
}

Node.js

node/selection-input/on-widget-update.js
/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          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
            },
          ]
        }
      }
    }
  };
}

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.