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, una scheda che viene visualizzata nella scheda Home dei 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 elaborare e rispondere di conseguenza. Per maggiori dettagli, vedi Raccogliere ed elaborare le informazioni degli utenti di Google Chat.

Utilizza Card Builder per progettare e visualizzare in anteprima le interfacce utente e di messaggistica per le app di chat:

Apri il generatore di schede

Prerequisiti

Un'app Google Chat configurata per ricevere e rispondere agli eventi di interazione. Per creare un'app di 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 sia testo che un'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 ulteriori informazioni.
  • 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 costituita da un widget ButtonList con due pulsanti. Un pulsante apre la documentazione per 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 viene visualizzato un insieme di pulsanti in diversi stili di pulsanti Material Design.

Per applicare lo stile Material Design, non includere l'attributo "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 visualizzata 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 visualizzata una scheda costituita da un widget ButtonList con due widget Button 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.

Aggiungere un pulsante con un'icona e del testo

Di seguito è mostrata 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 gamma 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

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

Aggiungere un elenco di chip

Il widget ChipList offre un modo versatile e visivamente accattivante per visualizzare le informazioni. Utilizza elenchi di chip per rappresentare tag, categorie o altri dati pertinenti, in modo che gli utenti possano navigare e interagire più facilmente 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 i dati inseriti dagli utenti, consulta Raccogliere ed elaborare le informazioni degli utenti di Google Chat.

Raccogliere 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 on-change, che sono Actions che vengono eseguite quando si verifica una modifica nel campo di input di testo, ad esempio quando un utente aggiunge o elimina del testo.

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

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

Raccogliere date o orari

Il widget DateTimePicker consente agli utenti di inserire una data, un orario o entrambi. 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 invita gli utenti a inserire le informazioni correttamente.

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

Consenti agli utenti di selezionare gli elementi

Il widget SelectionInput fornisce un insieme di elementi selezionabili, come caselle di controllo, pulsanti di opzione, interruttori o un menu a discesa. Puoi utilizzare 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 le azioni on-change, che sono Actions che vengono eseguite quando si verifica una modifica in un campo di input di selezione, ad esempio quando un utente seleziona o deseleziona un elemento.

Le app di chat possono ricevere ed elaborare il valore degli articoli selezionati. Per informazioni dettagliate sull'utilizzo degli input dei moduli, vedi 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 le 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 pulsanti di opzione:

Aggiungere un interruttore

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 i pulsanti di attivazione/disattivazione:

Di seguito 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:

Aggiungere un menu multiselezione

Di seguito viene visualizzata una scheda che chiede all'utente di selezionare i contatti da un menu di selezione multipla:

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

  • Utenti di Google Workspace: puoi popolare solo gli utenti all'interno della stessa organizzazione Google Workspace.
  • Spazi di Chat: l'utente che inserisce elementi nel menu multiselezione 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 di altri tipi di input di selezione, ometti gli oggetti SelectionItem, perché questi elementi di selezione provengono dinamicamente da Google Workspace.

Il seguente codice mostra un menu a 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 a selezione multipla degli spazi Chat. Per compilare gli spazi, l'input di selezione specifica il campo hostAppDataSource. Il menu 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 essere compilati con elementi provenienti da un'origine dati esterna o di terze parti. Ad esempio, puoi utilizzare i menu a selezione multipla per aiutare un utente a scegliere 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 restituisce elementi dall'origine dati.

Per ridurre le richieste a un'origine dati esterna, puoi includere gli elementi suggeriti che vengono visualizzati nel menu a selezione multipla prima che gli utenti digitino nel menu. 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 a selezione multipla di elementi di un insieme esterno di contatti per l'utente. Il menu mostra un contatto per impostazione predefinita ed 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 popola le città degli Stati Uniti, la tua app di 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 dati esterna e restituisce gli elementi ogni volta che un utente digita nel menu di selezione multipla. La funzione deve:

  • Passa un oggetto evento che rappresenta l'interazione dell'utente con il menu.
  • Identifica che il valore invokedFunction dell'evento di interazione corrisponde alla funzione del campo externalDataSource.
  • Quando le funzioni corrispondono, restituisci gli elementi suggeriti dall'origine dati esterna. Per suggerire elementi in base a ciò che digita l'utente, recupera 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 dati esterna. Utilizzando l'esempio precedente, l'app Chat suggerisce 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 in un action e nei widget di una scheda. Ad esempio, puoi verificare che un campo di input di testo contenga il testo inserito dall'utente o un determinato numero di caratteri.

Impostare i widget richiesti per le azioni

Nell'ambito di action della scheda, aggiungi i nomi dei widget necessari per un'azione all'elenco requiredWidgets.

Se uno dei widget elencati qui non ha un valore quando viene richiamata questa azione, l'invio dell'azione del modulo viene annullato.

Quando "all_widgets_are_required": "true" è impostato per un'azione, tutti i widget nella scheda sono richiesti da questa azione.

Impostare 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 in dateTimePicker

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 inserimento di testo

Nel campo di convalida del widget textInput, è possibile specificare il limite di caratteri e il tipo di input per questo widget di input di testo.

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

Anche se nell'interfaccia utente di Chat potrebbe non essere visualizzato un messaggio di errore, sono disponibili messaggi di errore descrittivi e dati di log per aiutarti a correggere gli errori quando la registrazione degli errori per le app di chat è attivata. Per assistenza nella visualizzazione, nel debug e nella correzione degli errori, consulta Risolvere i problemi e correggere gli errori di Google Chat.