En esta página, se explica cómo agregar widgets y elementos de la IU a mensajes de tarjetas o diálogos para que los usuarios puedan interactuar con tu app de Google Chat, por ejemplo, haciendo clic en un botón o enviando información.
Usa Card Builder para diseñar mensajes de tarjetas JSON y obtener una vista previa de ellos para apps de Chat:
Abre el Creador de tarjetasRequisitos previos
Cómo agregar un botón
El widget ButtonList
muestra un conjunto de botones. Los botones pueden mostrar texto, un ícono o ambos. Cada Button
admite una acción OnClick
que se produce cuando los usuarios hacen clic en el botón. Por ejemplo:
- Abre un hipervínculo con
OpenLink
para proporcionarles a los usuarios información adicional. - Ejecutar un
action
que ejecute 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"
.
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 color de fondo del botón. El otro botón se desactiva con el campo Disabled
, lo que evita que el usuario haga clic en él 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 ButtonList
con dos widgets de ícono Button
. Un botón usa el campo knownIcon
para mostrar el ícono de correo electrónico integrado de Google Chat. El otro botón usa el campo iconUrl
para mostrar un widget de ícono personalizado.
Cómo agregar un botón con un ícono y texto
A continuación, se muestra una tarjeta que consta de un widget ButtonList
que le solicita al usuario que envíe un correo electrónico. El primer botón muestra un ícono de correo electrónico y el segundo muestra texto. El usuario puede hacer clic en el ícono o en el botón de texto para ejecutar la función sendEmail
.
Cómo agregar elementos seleccionables de la IU
El widget 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. Para recopilar datos indefinidos de los usuarios, usa el widget TextInput
en su lugar.
El widget de SelectionInput
admite sugerencias, que ayudan a los usuarios a ingresar datos uniformes, y acciones de cambio, que son Actions
, que se ejecutan cuando se produce un cambio en un campo de entrada de selección, como cuando un usuario selecciona un elemento o anula la selección.
Las apps de chat pueden recibir y procesar el valor de los elementos seleccionados. Si quieres obtener más información para trabajar con entradas de formularios, consulta Recibe datos de formularios.
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:
- Casillas de verificación
- Botones de selección
- Interruptores
- Menú desplegable
- Menú de selección múltiple
Agregar una casilla de verificación
A continuación, se muestra un diálogo en el que se le pide al usuario que especifique si un contacto es profesional, personal o ambos, con un widget SelectionInput
que usa casillas de verificación:
Agrega un botón de selección
A continuación, se muestra un diálogo en el que se le pide al usuario que especifique si un contacto es profesional o personal con un widget SelectionInput
que usa botones de selección:
Agrega un interruptor
A continuación, se muestra un diálogo en el que se le pide al usuario que especifique si un contacto es profesional, personal o ambos con un widget SelectionInput
que usa interruptores:
Agrega un menú desplegable
A continuación, se muestra un diálogo en el que se le pide al usuario que especifique si un contacto es profesional o personal con un widget SelectionInput
que usa un menú desplegable:
Agrega un menú de selección múltiple
A continuación, se muestra un diálogo en el que se le solicita al usuario que elija los contactos de un menú de selección múltiple:
Usar fuentes de datos para menús de selección múltiple
En la siguiente sección, se explica cómo usar los menús de selección múltiple para propagar datos de fuentes dinámicas, como una aplicación de Google Workspace o una fuente de datos externa.
Fuentes de datos de Google Workspace
Puedes propagar elementos para un menú de selección múltiple a partir de las siguientes fuentes de datos en Google Workspace:
- Usuarios de Google Workspace: Solo puedes propagar usuarios dentro de la misma organización de Google Workspace.
- Espacios de Chat: El usuario que ingresa los elementos en el menú de selección múltiple solo puede ver y seleccionar los espacios a los que pertenece dentro de su organización de Google Workspace.
Para usar las fuentes de datos de Google Workspace, especifica el campo platformDataSource
. A diferencia de otros tipos de entrada de selección, omites objetos SectionItem
, ya que estos elementos de selección se obtienen de forma dinámica de 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 espacios de Chat. Para propagar espacios, la entrada de selección especifica el campo hostAppDataSource
. El menú de selección múltiple también establece defaultToCurrentSpace
en true
, lo que hace que el espacio actual sea la selección predeterminada:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
Fuentes de datos fuera de Google Workspace
Los menús de selección múltiple también pueden propagar elementos a partir de una fuente de datos de terceros o externa. Por ejemplo, puedes usar menús de selección múltiple para ayudar a un usuario a seleccionar de una lista de posibles clientes comerciales desde un sistema de administración de relaciones con clientes (CRM).
Si quieres usar una fuente de datos externa, usa el campo externalDataSource
para especificar 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 en 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 los objetos SelectionItem
.
En el siguiente código, se muestra un menú de selección múltiple de elementos de 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 la 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 los usuarios comienzan a escribir en el menú de selección múltiple. Por ejemplo, si un usuario comienza a escribir Atl
para un menú que propaga datos en ciudades de Estados Unidos, tu app de Chat puede sugerir automáticamente Atlanta
antes de que el usuario termine de escribir. Puedes autocompletar hasta 100 elementos.
Para autocompletar elementos, crea una función que consulte la fuente de datos externa y muestre elementos cada vez que un usuario escriba en el menú de selección múltiple. La función debe hacer lo siguiente:
- Pasa un objeto de evento que represente la interacción del usuario con el menú.
- Identifica que el valor
invokedFunction
del evento de interacción coincide con la función del campoexternalDataSource
. - Cuando las funciones coincidan, muestra los elementos sugeridos de la fuente de datos externa. Para sugerir elementos según lo que escribe el usuario, obtén el valor de la clave
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 en función del
momento en que se activa la función getContacts
:
Apps Script
Node.js
Agrega un campo en el que el usuario pueda ingresar texto
El widget TextInput
proporciona un campo en el que los usuarios pueden ingresar texto. El widget admite sugerencias, que ayudan a los usuarios a ingresar datos uniformes, y acciones de cambio, que son Actions
, que se ejecutan cuando se produce un cambio en el campo de entrada de texto, como cuando un usuario agrega o borra texto.
Cuando necesites recopilar datos abstractos o desconocidos de los usuarios, usa este widget de TextInput
. Para recopilar datos definidos de los usuarios, usa el widget SelectionInput
en su lugar.
Para procesar el texto que ingresan los usuarios, consulta Cómo recibir datos del formulario.
La siguiente es una tarjeta que consta de un widget de TextInput
:
Permite que el usuario elija una fecha y una hora
El widget DateTimePicker
permite a los usuarios ingresar una fecha, una hora o ambas. O bien, los usuarios pueden utilizar el selector para seleccionar fechas y horas. Si los usuarios ingresan una hora o fecha no válida, el selector muestra un error que les solicita que ingresen la información de forma correcta.
Para procesar los valores de fecha y hora que ingresan los usuarios, consulta Cómo recibir datos del formulario.
En el siguiente ejemplo, se muestra una tarjeta que consta de tres tipos diferentes de widgets de DateTimePicker
:
Valida los datos ingresados en las tarjetas
En esta página, se explica cómo validar los datos que se ingresan al action
y los widgets de una tarjeta.
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 los widgets que necesita una acción a su lista requiredWidgets
.
Si alguno de los widgets enumerados aquí no tiene un valor cuando se invoca esta acción, se cancela el envío de la acción del formulario.
Cuando se configura "all_widgets_are_required": "true"
para una acción, esta acción requiere todos los widgets de la tarjeta.
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 el campo de validación del widget textInput
, se puede especificar el límite de caracteres y el tipo de entrada para 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 o una tarjeta de Google Chat muestran un error, la interfaz de Chat muestra el mensaje “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 o la tarjeta de Chat producen un resultado inesperado. Por ejemplo, puede que no aparezca un mensaje de tarjeta.
Aunque es posible que un mensaje de error no aparezca en la IU de Chat, hay mensajes de error descriptivos y datos de registro disponibles para ayudarte a corregir errores cuando está activado el registro de errores para las apps de Chat. Si necesitas ayuda para ver, depurar y corregir errores, consulta Cómo solucionar problemas y corregir errores de Google Chat.