Progetta una scheda o una finestra di dialogo interattiva

In questa pagina viene spiegato come aggiungere widget ed elementi dell'interfaccia utente a messaggi di schede o finestre di dialogo in modo che gli utenti possano interagire con la tua app Google Chat, ad esempio facendo clic su un pulsante o inviando informazioni.

Progetta e visualizza l'anteprima delle schede con Card Builder.

Apri Card Builder

Prerequisiti

  • Un account Google Workspace con accesso a Google Chat.
  • Un'app di Chat pubblicata. Per creare un'app di Chat, segui questa quickstart.

    • Aggiungi un pulsante

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

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

    Aggiungi un pulsante che esegue una funzione personalizzata

    Quella che segue è una scheda costituita 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".

    Aggiungere un pulsante con un 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 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 mostrata una scheda costituita da un widget ButtonList con due widget icona Button. Un pulsante utilizza il campo knownIcon per visualizzare l'icona dell'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 mostrata una scheda costituita da un widget ButtonList che richiede all'utente di inviare un'email. Il primo pulsante mostra un'icona di email, mentre il secondo mostra del testo. L'utente può fare clic sull'icona o sul pulsante di testo per eseguire la funzione sendEmail.

    Aggiungi elementi UI 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, utilizza invece il widget TextInput.

    Il widget SelectionInput supporta i suggerimenti, che aiutano gli utenti a inserire dati uniformi, e 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 dei moduli, consulta Ricevere dati dei moduli.

    Questa sezione fornisce esempi di schede che utilizzano il widget SelectionInput. Gli esempi utilizzano diversi tipi di input di 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 le 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 usa 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:

    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 completare i dati dalle origini dinamiche, come un'applicazione Google Workspace o un'origine dati esterna.

    Origini dati di Google Workspace

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

    • Utenti Google Workspace: puoi inserire solo gli utenti appartenenti alla stessa organizzazione Google Workspace.
    • Spazi di Chat: l'utente che inserisce le voci nel menu di selezione multipla può solo visualizzare e selezionare gli spazi a cui appartiene all'interno della propria organizzazione Google Workspace.

    Per utilizzare le origini dati Google Workspace, devi specificare il campo platformDataSource. A differenza degli altri tipi di input di selezione, gli oggetti SectionItem vengono omessi, poiché questi elementi di selezione vengono recuperati dinamicamente da Google Workspace.

    Il seguente codice mostra un menu a selezione multipla di 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 di spazi di Chat. Per compilare gli spazi, l'input di selezione specifica il campo hostAppDataSource. Il menu di selezione multipla 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
          }
        }
      }
    }
  }
}
    Origini dati esterne a Google Workspace

    I menu a selezione multipla possono completare gli elementi anche da un'origine dati di terze parti o esterna. Ad esempio, puoi utilizzare i 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, usa 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 digitino il menu. 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 seguente codice mostra un menu a selezione multipla di elementi da un insieme di contatti esterno per l'utente. Il menu visualizza un contatto per impostazione predefinita ed esegue la funzione getContacts per recuperare e completare 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 compila le città negli Stati Uniti, l'app Chat può suggerirti 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 nell'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 rappresenti l'interazione dell'utente con il menu.
    • Verifica che il valore invokedFunction dell'evento di interazione corrisponda 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 l'utente digita, ottieni il valore per la chiave autocomplete_widget_query. Questo valore rappresenta ciò che l'utente digita nel menu.

    Il codice seguente completa automaticamente gli elementi da una risorsa dati esterna. Utilizzando l'esempio precedente, l'app di Chat suggerisce elementi in base a 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
            },
          ]
        }
      }
    }
  };
}

    Aggiungi un campo in cui l'utente può inserire del testo

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

    Quando devi raccogliere dati astratti o sconosciuti dagli 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 dati dei moduli.

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

    Consentire a un utente di scegliere una data e un'ora

    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 richiede agli utenti di inserire le informazioni correttamente.

    Per elaborare i valori di data e ora inseriti dagli utenti, vedi Ricevere dati dei moduli.

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

    Risolvi il problema

    Quando un'app o una scheda Google Chat restituisce un errore, nell'interfaccia di Chat viene visualizzato il messaggio "Si è verificato un problema" o "Impossibile elaborare la richiesta". A volte nell'interfaccia utente di Chat non vengono visualizzati messaggi di errore, ma l'app o la scheda Chat produce un risultato imprevisto; ad esempio, è possibile che non venga visualizzato un messaggio di scheda.

    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 la registrazione degli errori per le app di Chat è attivata. Per informazioni su visualizzazione, debug e correzione degli errori, consulta l'articolo Risolvere gli errori di Google Chat.