Aggiungere elementi interattivi dell'interfaccia utente alle schede

Questa pagina spiega come aggiungere widget ed elementi dell'interfaccia utente alle schede in modo che gli utenti possano interagire con la tua app Google Chat, ad esempio facendo clic su un pulsante o inviando 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, ovvero una scheda visualizzata nella scheda Home nei messaggi diretti con l'app Chat.
  • Finestre di dialogo, ovvero schede che si aprono in una nuova finestra da messaggi e home page.

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

Utilizza lo strumento per la creazione di schede per progettare e visualizzare l'anteprima di interfacce utente e messaggistica per le app di chat:

Apri lo strumento per la creazione di schede

Prerequisiti

Un'app Google Chat per cui sono abilitate le funzionalità interattive. Per creare un'app Chat interattiva, completa una delle seguenti guide rapide in base all'architettura dell'app che vuoi utilizzare:

Aggiungere un pulsante

Il widget ButtonList mostra un insieme di pulsanti. I pulsanti possono mostrare testo, un'icona o testo e icona. Ogni 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 action che esegue una funzione personalizzata, ad esempio la chiamata di un'API.

Per l'accessibilità, i pulsanti supportano il testo alternativo.

Aggiungere 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 chiamata goToView() e passa il parametro viewType="BIRD EYE VIEW".

Aggiungere un pulsante con lo stile Material Design

Di seguito è riportato un insieme di pulsanti in diversi stili di pulsanti Material Design.

Per applicare lo stile Material Design, non includere l'attributo "colore".

Aggiungere 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 visualizzata una scheda composta da un widget ButtonList con due pulsanti. Un pulsante utilizza il campo Color per personalizzare il colore 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 visualizzata una scheda composta da un widget ButtonList con due widget Button con icone. 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.

Aggiungere un pulsante con un'icona e del testo

Viene visualizzata una scheda composta da un widget ButtonList che chiede all'utente di inviare un'email. Il primo pulsante mostra un'icona email e il secondo pulsante mostra del testo. L'utente può fare clic sull'icona o sul pulsante di testo per eseguire la funzione sendEmail.

Personalizzare il pulsante per una sezione comprimibile

Personalizza il pulsante di controllo che comprime ed espande le sezioni all'interno di una scheda. Scegli tra una serie di icone o immagini per rappresentare visivamente i contenuti della sezione, in modo che gli utenti possano comprendere e interagire più facilmente con le informazioni.

Aggiungere un menu extra

Overflow menu può essere utilizzato nelle schede di Chat per offrire opzioni e azioni aggiuntive. Consente di includere più opzioni senza ingombrare l'interfaccia della scheda, garantendo un design pulito e organizzato.

Aggiungi un elenco di chip

Il widget ChipList offre 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 da semplificare la navigazione e l'interazione degli utenti 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, vedi Raccogliere ed elaborare informazioni dagli utenti di Google Chat.

Raccogliere il testo

Il widget TextInput fornisce un campo in cui gli utenti possono inserire del testo. Il widget supporta i suggerimenti, che aiutano gli utenti a inserire dati uniformi, e le azioni al cambio, che sono Actions che vengono eseguite quando si verifica una modifica nel campo di immissione di testo, ad esempio quando un utente aggiunge o elimina del testo.

Quando devi raccogliere dati astratti o sconosciuti dagli utenti, utilizza questo TextInput widget. Per raccogliere dati definiti dagli utenti, utilizza invece il widget SelectionInput.

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

Raccogliere date o orari

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 li invita a inserire le informazioni correttamente.

Di seguito viene visualizzata una scheda composta da tre diversi tipi di widgetDateTimePicker:

Consentire agli utenti di selezionare gli elementi

Il widget SelectionInput fornisce un insieme di elementi selezionabili, come caselle di controllo, pulsanti di opzione, opzioni o un menu a discesa. Puoi utilizzare 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 al cambio, che vengono eseguite quando si verifica una modifica in un campo di immissione della selezione, ad esempio quando un utente seleziona o deseleziona un elemento.

Le app di chat possono ricevere ed elaborare il valore degli elementi selezionati. Per informazioni dettagliate sull'utilizzo degli input dei moduli, consulta Elaborare le informazioni inserite dagli utenti.

Questa sezione fornisce esempi di schede che utilizzano il widget SelectionInput. Gli esempi utilizzano diversi tipi di input di sezione:

Aggiungere una casella di controllo

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

Aggiungere un pulsante di opzione

Di seguito viene visualizzata una scheda 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 scheda che chiede all'utente di specificare se un contatto è professionale, personale o entrambi con un widget SelectionInput che utilizza sensori:

Viene visualizzata una scheda 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 scheda che chiede all'utente di selezionare i contatti da un menu a selezione multipla:

Puoi completare gli elementi di un menu a selezione multipla dalle seguenti origini dati in Google Workspace:

  • Utenti di Google Workspace: puoi inserire solo gli utenti all'interno 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 di selezione multipla degli 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 di selezione multipla degli spazi di Chat. Per compilare gli spazi, l'input di selezione specifica il campo hostAppDataSource. Il menu di multiselezione 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
          }
        }
      }
    }
  }
}

I menu a selezione multipla possono anche compilare gli elementi di un'origine dati di terze parti o esterna. Ad esempio, puoi utilizzare i menu di selezione multipla per aiutare un utente a scegliere da un elenco di lead di vendita di 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 gli elementi suggeriti che vengono visualizzati nel menu di selezione multipla prima che gli utenti inizino a digitare. Ad esempio, puoi compilare i contatti cercati di recente per l'utente. Per compilare gli elementi suggeriti da un'origine dati esterna, specifica gli oggetti SelectionItem.

Il seguente codice mostra un menu di selezione multipla di elementi di un insieme esterno di contatti per l'utente. Per impostazione predefinita, il menu mostra un contatto e esegue la funzione getContacts per recuperare e compilare gli elementi dall'origine dati esterna:

Node.js

node/selection-input/index.js
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

Python

python/selection-input/main.py
'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': "getContacts" },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_contact("3")]
}

Java

java/selection-input/src/main/java/com/google/chat/selectionInput/App.java
.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction("getContacts"))
  .setItems(List.of(getContact("3")))))))))));

Apps Script

apps-script/selection-input/selection-input.gs
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

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 mostra le 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, crea una funzione che esegue query sull'origine di 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.
  • Verifica che il valore di invokedFunction dell'evento di interazione corrisponda alla funzione del campo externalDataSource.
  • 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 ciò che l'utente digita nel menu.

Il seguente codice completa automaticamente gli elementi di una risorsa di dati esterna. Utilizzando l'esempio precedente, l'app Chat suggerisce gli elementi in base al momento in cui viene attivata la funzione getContacts:

Node.js

node/selection-input/index.js
/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
      // Only return items based on the query from the user
      ].filter(e => !query || e.text.includes(query))}}
    }};
  }
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Python

python/selection-input/main.py
def on_widget_update(event: dict) -> dict:
  """Responds to a WIDGET_UPDATE event in Google Chat."""
  if "getContacts" == event.get("common").get("invokedFunction"):
    query = event.get("common").get("parameters").get("autocomplete_widget_query")
    return { 'actionResponse': {
      'type': "UPDATE_WIDGET",
      'updatedWidget': { 'suggestions': { 'items': list(filter(lambda e: query is None or query in e["text"], [
        # The list is static here but it could be dynamic.
        get_contact("1"), get_contact("2"), get_contact("3"), get_contact("4"), get_contact("5")
      # Only return items based on the query from the user
      ]))}}
    }}


def get_contact(id: str) -> dict:
  """Generate a suggested contact given an ID."""
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

Java

java/selection-input/src/main/java/com/google/chat/selectionInput/App.java
// Responds to a WIDGET_UPDATE event in Google Chat.
Message onWidgetUpdate(JsonNode event) {
  if ("getContacts".equals(event.at("/invokedFunction").asText())) {
    String query = event.at("/common/parameters/autocomplete_widget_query").asText();
    return new Message().setActionResponse(new ActionResponse()
      .setType("UPDATE_WIDGET")
      .setUpdatedWidget(new UpdatedWidget()
        .setSuggestions(new SelectionItems().setItems(List.of(
          // The list is static here but it could be dynamic.
          getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
        // Only return items based on the query from the user
        ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList()))));
  }
  return null;
}

// Generate a suggested contact given an ID.
GoogleAppsCardV1SelectionItem getContact(String id) {
  return new GoogleAppsCardV1SelectionItem()
    .setValue(id)
    .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
    .setText("Contact " + id);
}

Apps Script

apps-script/selection-input/selection-input.gs
/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
      // Only return items based on the query from the user
      ].filter(e => !query || e.text.includes(query))}}
    }};
  }
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Convalidare i dati inseriti nelle schede

Questa pagina spiega come convalidare i dati inseriti nei 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 richiesti per le azioni

Nell'ambito di action della scheda, aggiungi i nomi dei widget di cui un'azione ha bisogno all'elenco requiredWidgets.

Se i widget elencati qui non hanno un valore quando viene invocata 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.

Impostare un'azione all_widgets_are_required in una 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"
          }
        }
      ]
    }
  ]
}
Impostare 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.

Impostare un limite di caratteri per un widget di immissione 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 o una scheda di Google Chat restituisce un errore, l'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la richiesta". A volte l'interfaccia utente di Chat non mostra alcun messaggio di errore, ma l'app Chat o la scheda produce un risultato imprevisto; ad esempio, un messaggio della scheda potrebbe non essere visualizzato.

Sebbene 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 la registrazione degli errori per le app Chat è attivata. Per assistenza su come visualizzare, eseguire il debug e correggere gli errori, consulta la sezione Risolvere gli errori di Google Chat.