Cómo agregar elementos interactivos de la IU a las tarjetas

En esta página, se explica cómo agregar widgets y elementos de IU a las tarjetas para que los usuarios puedan interactuar con tu app de Google Chat, por ejemplo, hacer clic en un botón o enviar información.

Las apps de Chat pueden usar las siguientes interfaces de Chat para crear tarjetas interactivas:

  • Mensajes que contienen una o más tarjetas.
  • Páginas principales que es una tarjeta que aparece en la pestaña Página principal en mensajes con la app de Chat.
  • Diálogos, que son tarjetas que se abren en una nueva ventana desde los mensajes y las páginas principales.

Cuando los usuarios interactúan con tarjetas, las apps de Chat pueden usar los datos que que reciben para procesar y responder en consecuencia. Para obtener más información, consulta Recopila y procesa información de los usuarios de Google Chat.


Usa Card Builder para diseñar y obtener una vista previa de las interfaces de usuario y mensajería para apps de Chat:

Abre el Creador de tarjetas

Requisitos previos

Una app de Google Chat habilitada para funciones interactivas. Para crear un app de Chat interactiva, completa una de las siguientes guías de inicio rápido en la arquitectura de app que quieres usar:

Agrega un botón

El Widget ButtonList muestra un conjunto de botones. Los botones pueden mostrar texto, o un ícono o texto y un ícono. Cada Button admite un Acción OnClick que ocurre cuando los usuarios hacen clic en el botón. Por ejemplo:

  • Abre un hipervínculo con OpenLink: para proporcionar a los usuarios información adicional.
  • Ejecuta un action que ejecuta una función personalizada, como llamar a una API.

Por cuestiones de accesibilidad, los botones admiten texto alternativo.

Cómo agregar un botón que ejecute una función personalizada

La siguiente es una tarjeta que consta de un widget de ButtonList con dos botones. Un botón abre la documentación para desarrolladores de Google Chat en una pestaña nueva. El Otro botón ejecuta una función personalizada llamada goToView() y pasa el Parámetro viewType="BIRD EYE VIEW".

Cómo agregar un botón con el estilo de Material Design

A continuación, se muestra un conjunto de botones en diferentes botones de Material Design. estilos.

Para aplicar el estilo de Material Design, no incluyas el atributo "color". .

Agrega un botón con un color personalizado y uno desactivado

Para evitar que los usuarios hagan clic en un botón, configura "disabled": "true".

A continuación, se muestra una tarjeta que consta de un widget de ButtonList con dos botones. Un botón usa el Campo Color para personalizar el fondo del botón color. El otro botón se desactiva con el campo Disabled, que impide que el usuario haga clic en el botón y ejecute la función.

Cómo agregar un botón con un ícono

A continuación, se muestra una tarjeta que consta de un widget de ButtonList con dos íconos. Button widgets. Un botón usa el knownIcon para mostrar el ícono de correo electrónico integrado de Google Chat. El otro usa el iconUrl para mostrar un widget de ícono personalizado.

Cómo agregar un botón con un ícono y texto

En el siguiente ejemplo, se muestra una tarjeta que consta de un widget de ButtonList que solicita que el usuario envíe un correo electrónico. El primer botón muestra un ícono de correo electrónico y los el segundo botón muestra texto. El usuario puede hacer clic en el ícono o en el texto para ejecutar la función sendEmail.

Cómo personalizar el botón para una sección que se puede contraer

Personaliza el botón de control que contrae y expande secciones dentro de una tarjeta. Elige entre una variedad de iconos o imágenes para representar visualmente el el contenido de esta sección, lo que facilita a los usuarios la comprensión e interacción la información.

Agregar un menú ampliado

El Overflow menu se pueden usar en las tarjetas de Chat para ofrecer opciones y acciones adicionales. Te permite incluir más opciones sin saturar la interfaz de la tarjeta, lo que garantiza una diseño limpio y organizado.

Cómo agregar una lista de chips

El ChipList proporciona una forma versátil y visualmente atractiva de mostrar la información. Usa listas de chips para representar etiquetas, categorías y otros datos relevantes, lo que sea más fácil para los usuarios navegar e interactuar con tu contenido.

Recopilar información de los usuarios

Esta sección explica cómo puedes agregar widgets que recopilen información, como texto o selecciones.

Para obtener información sobre cómo procesar lo que ingresan los usuarios, consulta Recopila y procesa información de los usuarios de Google Chat.

Cómo recopilar texto

El widget de TextInput proporciona un campo en el que los usuarios pueden ingresar texto. El el widget admite sugerencias, que ayudan a los usuarios a ingresar datos uniformes y, ante cambios, acciones, que son Actions que se ejecutan cuando se produce un cambio en el campo de entrada de texto, como cuando un usuario agrega o borrar texto.

Cuando necesites recopilar datos abstractos o desconocidos de los usuarios, usa este Widget TextInput. Para recopilar datos definidos de los usuarios, usa el SelectionInput widget en su lugar.

La siguiente es una tarjeta que consta de un widget de TextInput:

Recopilar fechas u horas

El Widget DateTimePicker permite a los usuarios ingresar una fecha, una hora o ambas una vez. O bien, los usuarios pueden utilizar el selector para seleccionar fechas y horas. Si los usuarios ingresan una fecha u hora no válida, el selector muestra un error que les solicita a los usuarios que correctamente la información.

A continuación, se muestra una tarjeta que consta de tres tipos diferentes de Widgets de DateTimePicker:

Permite que los usuarios seleccionen elementos

El widget de SelectionInput proporciona un conjunto de elementos seleccionables, como casillas de verificación, botones de selección, interruptores, o un menú desplegable. Puedes usar este widget para recopilar datos definidos y estandarizados de los usuarios. Recopilar datos indefinidos de los usuarios, usa el widget TextInput en su lugar.

El widget SelectionInput admite sugerencias, que ayudan a los usuarios a ingresar de manera uniforme. de Google y las acciones ante el cambio, que son Actions que se ejecutan cuando se produce un cambio en un campo de entrada de selección, como un seleccionar un elemento o anular la selección de este.

Las apps de chat pueden recibir y procesar el valor de los elementos seleccionados. Para obtener detalles sobre cómo trabajar con entradas de formularios, consulta Procesa la información que ingresan los usuarios.

En esta sección, se proporcionan ejemplos de tarjetas que usan el widget SelectionInput. En los ejemplos, se usan diferentes tipos de entradas de sección:

Agregar una casilla de verificación

A continuación, se muestra una tarjeta en la que se le pide al usuario que especifique si un contacto es profesional, personal o ambos, con un widget de SelectionInput que utiliza casillas de verificación:

Agrega un botón de selección

A continuación, se muestra una tarjeta en la que se le pide al usuario que especifique si un contacto es profesional o personal con un widget de SelectionInput que usa Botones de selección:

Agrega un interruptor

A continuación, se muestra una tarjeta en la que se le pide al usuario que especifique si un contacto es profesional, personal o ambos con un widget de SelectionInput que utiliza interruptores:

A continuación, se muestra una tarjeta en la que se le pide al usuario que especifique si un contacto es profesional o personal con un widget de SelectionInput que usa un menú desplegable:

Agrega un menú de selección múltiple

A continuación, se muestra una tarjeta en la que se le pide al usuario que seleccione contactos desde un menú de selección múltiple:

Puedes propagar elementos para un menú de selección múltiple a partir de los siguientes datos. en Google Workspace:

  • Usuarios de Google Workspace: Solo puedes propagar usuarios en el misma organización de Google Workspace.
  • Espacios de Chat: El usuario ingresa los elementos en la selección múltiple. solo pueden ver y seleccionar los espacios a los que pertenecen en su organización de Google Workspace.

Para usar las fuentes de datos de Google Workspace, especifica la platformDataSource . A diferencia de otros tipos de entrada de selección, se omiten SectionItem ya que estos elementos de selección se obtienen dinámicamente en Google Workspace.

El siguiente código muestra un menú de selección múltiple de usuarios de Google Workspace. Para propagar usuarios, la entrada de selección establece commonDataSource en USER:

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

En el siguiente código, se muestra un menú de selección múltiple de Chat y espacios. Para rellenar espacios, la entrada de selección especifica los hostAppDataSource. El menú de selección múltiple también establece defaultToCurrentSpace por true, lo que hace que el espacio actual sea el predeterminado en el menú:

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Los menús de selección múltiple también pueden propagar elementos a partir de datos de terceros o externos fuente. Por ejemplo, puedes usar menús de selección múltiple para ayudar a un usuario a seleccionar de un de posibles clientes comerciales desde un sistema de administración de relaciones con clientes (CRM).

Si quieres usar una fuente de datos externa, debes usar el campo externalDataSource para especifica una función que muestre elementos de la fuente de datos.

Para reducir las solicitudes a una fuente de datos externa, puedes incluir elementos sugeridos que aparecen en el menú de selección múltiple antes de que los usuarios escriban el menú. Por ejemplo, puedes propagar los contactos buscados recientemente para el usuario. Para propagar los elementos sugeridos a partir de una fuente de datos externa, especifica SelectionItem objetos.

El siguiente código muestra un menú de selección múltiple de elementos de una un conjunto externo de contactos para el usuario. El menú muestra un contacto de forma predeterminada. y ejecuta la función getContacts para recuperar y propagar elementos de fuente de datos externa:

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
      }
    ]
  }
}

Para las fuentes de datos externas, también puedes autocompletar los elementos que inician los usuarios escribiendo en el menú de selección múltiple. Por ejemplo, si un usuario comienza a escribir Atl para una de Google que propaga las ciudades de Estados Unidos, las La app de Chat puede sugerir automáticamente Atlanta antes que el usuario termina de escribir. Puedes autocompletar hasta 100 elementos.

Para autocompletar elementos, creas una función que consulta los datos externos fuente y muestra elementos cada vez que un usuario escribe en el menú de selección múltiple. El debe hacer lo siguiente:

  • Pasa un objeto de evento que represente la interacción del usuario con el menú.
  • Identifica que el nombre del evento de interacción invokedFunction de salida coincide con la función del campo externalDataSource.
  • Cuando las funciones coinciden, se muestran los elementos sugeridos a partir de los datos externos fuente. Para sugerir elementos en función de lo que escribe el usuario, obtén el valor del atributo Tecla autocomplete_widget_query. Este valor representa lo que el usuario escribe en el menú.

El siguiente código autocompleta elementos de un recurso de datos externo. Con el ejemplo anterior, la app de Chat sugiere elementos según Cuando se activa la función 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
            },
          ]
        }
      }
    }
  };
}

Valida los datos ingresados en las tarjetas

En esta página, se explica cómo validar los datos ingresados en el action de una tarjeta. y widgets. Por ejemplo, puedes validar que un campo de entrada de texto tenga texto ingresado por el usuario o que contenga una cierta cantidad de caracteres.

Configura los widgets necesarios para realizar acciones

Como parte del action de la tarjeta, Agrega nombres de widgets que necesita una acción a su lista requiredWidgets.

Si alguno de los widgets de esta lista no tiene un valor cuando se invoca esta acción, se cancela el envío de la acción del formulario.

Cuando se establece "all_widgets_are_required": "true" para una acción, todos los widgets en la tarjeta son obligatorios para esta acción.

Establece una acción all_widgets_are_required en la selección múltiple

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
              }
            ]
          }
        }
      ]
    }
  ]
}
Establece una acción all_widgets_are_required en el selector de fecha y hora

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"
          }
        }
      ]
    }
  ]
}
Establece una acción all_widgets_are_required en el menú desplegable

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
              }
            ]
          }
        }
      ]
    }
  ]
}

Cómo establecer la validación para un widget de entrada de texto

En la textInput de validación del widget, puedes especificar el límite de caracteres y el tipo de entrada este widget de entrada de texto.

Cómo establecer un límite de caracteres para un widget de entrada de texto

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
            }
          }
        }
      ]
    }
  ]
}
Cómo configurar el tipo de entrada para un widget de entrada de texto

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"
            }
          }
        }
      ]
    }
  ]
}

Solucionar problemas

Cuando una app de Google Chat o card muestra un error, el En la interfaz de Chat, aparece un mensaje que dice “Se produjo un error”. o "No se pudo procesar la solicitud". A veces, la IU de Chat no muestra ningún mensaje de error, pero la app de Chat la tarjeta produce un resultado inesperado; Por ejemplo, es posible que un mensaje de tarjeta no para que aparezca la opción.

Aunque es posible que no aparezca un mensaje de error en la IU de Chat, Hay mensajes de error descriptivos y datos de registro disponibles para ayudarte a corregir errores. Cuando se activa el registro de errores de las apps de Chat. Para obtener ayuda sobre la visualización, la depuración y la corrección de errores, consulta Soluciona problemas y corrige errores de Google Chat.