Un widget es un elemento simple de la IU que proporciona uno o más de los siguientes elementos:
- Estructura para otros widgets, como tarjetas y secciones,
- Información al usuario, como texto e imágenes
- Ventajas de la acción, como botones, campos de entrada de texto o casillas de verificación
Los conjuntos de widgets que se agregan a las secciones de la tarjeta definen la IU general del complemento. Los widgets tienen la misma apariencia y función en dispositivos web y móviles. En la documentación de referencia, se describen varios métodos para compilar conjuntos de widgets.
Usa el kit de diseño de complementos de Google Workspace
Para ahorrar tiempo en el diseño de widgets de complementos, los diseñadores pueden usar el kit de diseño de IU de complementos de Google Workspace disponible en Figma. Puedes crear una cuenta de Figma o solicitar una licencia al administrador de tu organización.
Explora los componentes y usa plantillas integradas para crear y visualizar widgets.
Tipos de widgets
Por lo general, los widgets de complementos se clasifican en tres grupos: widgets estructurales, widgets informativos y widgets de interacción del usuario.
Widgets estructurales
Los widgets estructurales proporcionan contenedores y organización para los otros widgets que se usan en la IA.
- Conjunto de botones: Es una colección de uno o más botones de texto o imagen agrupados en una fila horizontal.
- Tarjeta: Tarjeta única de contexto que contiene una o más secciones de tarjeta. Para definir cómo se pueden mover los usuarios entre las tarjetas, configura la navegación de tarjetas.
- Encabezado de la tarjeta: Es el encabezado para una tarjeta determinada. Los encabezados de las tarjetas pueden tener títulos, subtítulos y una imagen. Las acciones de la tarjeta y las acciones universales aparecen en el encabezado de la tarjeta si el complemento las usa.
- Sección de tarjetas: Es un grupo de widgets que se recopila dividido por secciones de la tarjeta por una regla horizontal y, opcionalmente, por un encabezado de sección. Cada tarjeta debe tener al menos una sección. No puedes agregar tarjetas ni encabezados de tarjetas a una sección de tarjeta.
Además de estos widgets estructurales básicos, en un complemento de Google Workspace, puedes usar el servicio de tarjetas para crear estructuras que se superpongan con la tarjeta actual: pies de página fijos y tarjetas de visualización:
Pie de página fijo
Ahora puedes agregar una fila fija de botones a la parte inferior de tu tarjeta. Esta fila no se mueve ni se desplaza con el resto del contenido de la tarjeta. En el siguiente fragmento de código, se muestra cómo definir un pie de página fijo de ejemplo y agregarlo a una tarjeta:
var fixedFooter = CardService.newFixedFooter()
.setPrimaryButton(
CardService.newTextButton()
.setText("help")
.setOpenLink(CardService.newOpenLink()
.setUrl("https://www.google.com")))
.setSecondaryButton(
CardService.newTextButton()
.setText("submit")
.setOnClickAction(
CardService.newAction()
.setFunctionName(
"submitCallback")));
var card = CardService.newCardBuilder()
// (...)
.setFixedFooter(fixedFooter)
.build();
|
|
Mostrar tarjeta
Cuando una acción del usuario activa un contenido contextual nuevo, como abrir un mensaje de Gmail, puedes mostrar el contenido contextual nuevo de inmediato (comportamiento predeterminado) o mostrar una notificación con tarjeta en la parte inferior de la barra lateral. Si un usuario hace clic en Atrás para volver a tu página principal mientras está activado un activador contextual, aparecerá una tarjeta de ayuda para que los usuarios vuelvan a encontrar el contenido contextual.
Para mostrar una tarjeta de vista previa cuando haya nuevo contenido contextual disponible, en lugar de mostrarlo de inmediato, agrega .setDisplayStyle(CardService.DisplayStyle.PEEK) a tu clase CardBuilder. Una tarjeta de vista previa solo aparece si se muestra un solo objeto de tarjeta con el activador contextual; de lo contrario, las tarjetas que se muestran reemplazan de inmediato la tarjeta actual.
Para personalizar el encabezado de la tarjeta de vista previa, agrega el método .setPeekCardHeader() con un objeto CardHeader estándar cuando compiles tu tarjeta contextual. De forma predeterminada, el encabezado de una tarjeta Peek contiene solo el nombre de tu complemento.
El siguiente código, que se basa en la Guía de inicio rápido del complemento de Google Workspace para Cats, notifica a los usuarios sobre el nuevo contenido contextual con una tarjeta de Peek y personaliza el encabezado de la tarjeta para mostrar el asunto del subproceso de mensaje de Gmail seleccionado.
var peekHeader = CardService.newCardHeader()
.setTitle('Contextual Cat')
.setImageUrl('https://www.gstatic.com/images/
icons/material/system/1x/pets_black_48dp.png')
.setSubtitle(text);
. . .
var card = CardService.newCardBuilder()
.setDisplayStyle(CardService.DisplayStyle.PEEK)
.setPeekCardHeader(peekHeader);
|
|
Widgets informativos
Los widgets informativos presentan información al usuario.
- Imagen: Una imagen indicada por una URL alojada y de acceso público que proporcionas.
- DecoratedText: Es una string de contenido de texto que puedes vincular con otros elementos, como etiquetas de texto inferiores y superiores, y una imagen o un ícono. Los widgets de DecoratedText también pueden incluir un widget Button o Switch. Los interruptores agregados pueden ser simples o casillas de verificación. El texto de contenido del widget DecoratedText puede usar formato HTML; las etiquetas inferior y superior deben usar texto sin formato.
- Párrafo de texto: Es un párrafo de texto simple que puede incluir elementos con formato HTML.
Widgets de interacción del usuario
Los widgets de interacción del usuario permiten que el complemento responda a las acciones que realizan los usuarios. Puedes configurar estos widgets con respuestas de acción para mostrar diferentes tarjetas, abrir URL, mostrar notificaciones, redactar correos electrónicos de borrador o ejecutar otras funciones de Apps Script. Consulta la guía Cómo compilar tarjetas interactivas para obtener más detalles.
- Acción de la tarjeta: Es un elemento de menú ubicado en el menú de la barra de encabezado del complemento. El menú de la barra de encabezado también puede contener elementos definidos como acciones universales, que aparecen en cada tarjeta que define el complemento.
- Selectores de fecha y hora: Widgets que permiten a los usuarios seleccionar una fecha, una hora o ambas. Consulta Selectores de fecha y hora a continuación para obtener más información.
- Botón de imagen: Es un botón que usa una imagen en lugar de texto. Puedes usar uno de varios íconos predefinidos o una imagen alojada en público y indicada por su URL.
- Entrada de selección: Es un campo de entrada que representa una colección de opciones. Los widgets de entrada de selección se presentan como casillas de verificación, botones de selección o cuadros de selección desplegables.
- Interruptor: Es un widget de activación. Solo puedes usar interruptores junto con un widget DecoratedText. De forma predeterminada, se muestran como un interruptor, pero puedes hacer que se muestren como una casilla de verificación.
- Botón de texto: Un botón con una etiqueta de texto. Puedes especificar un relleno de color de fondo para los botones de texto (el valor predeterminado es transparente). También puedes inhabilitar el botón según sea necesario.
- Entrada de texto: Es un campo de entrada de texto. El widget puede tener texto del título, texto de la sugerencia y texto de varias líneas. El widget puede activar acciones cuando cambia el valor de texto.
- Cuadrícula: Es un diseño de varias columnas que representa una colección de elementos. Puedes representar elementos con una imagen, un título, un subtítulo y una variedad de opciones de personalización, como los estilos de borde y recorte.
Casillas de verificación de DecoratedText
Puedes definir un widget DecoratedText que tenga una casilla de verificación adjunta, en lugar de un botón o un interruptor. Al igual que con los interruptores, el valor de la casilla de verificación se incluye en el objeto de evento de acción que el método setOnClickAction(action) pasa al Action.DecoratedText
En el siguiente fragmento de código, se muestra cómo definir un widget DecoratedText de casilla de verificación, que luego puedes agregar a una tarjeta:
var decoratedText = CardService.newDecoratedText()
// (...)
.setSwitch(CardService.newSwitch()
.setFieldName('form_input_switch_key')
.setValue('switch_is_on')
.setControlType(
CardService.SwitchControlType.CHECK_BOX));
|
|
Selectores de fecha y hora
Puedes definir widgets que les permitan a los usuarios seleccionar una hora, una fecha o ambas.
Puedes usar setOnChangeAction() para asignar una función del controlador de widgets que se ejecutará cuando cambie el valor del selector.
En el siguiente fragmento de código, se muestra cómo definir un selector de solo fecha y hora, y un selector de fecha y hora, que luego puedes agregar a una tarjeta:
var dateOnlyPicker = CardService.newDatePicker()
.setTitle("Enter the date.")
.setFieldName("date_field")
// Set default value as May 24 2019. Either a
// number or string is acceptable.
.setValueInMsSinceEpoch(1558668600000)
.setOnChangeAction(CardService.newAction()
.setFunctionName("handleDateChange"));
var timeOnlyPicker = CardService.newTimePicker()
.setTitle("Enter the time.")
.setFieldName("time_field")
// Set default value as 23:30.
.setHours(23)
.setMinutes(30)
.setOnChangeAction(CardService.newAction()
.setFunctionName("handleTimeChange"));
var dateTimePicker = CardService.newDateTimePicker()
.setTitle("Enter the date and time in EDT time.")
.setFieldName("date_time_field")
// Set default value as May 24 2019 03:30 AM UTC.
// Either a number or string is acceptable.
.setValueInMsSinceEpoch(1558668600000)
// EDT time is 4 hours behind UTC.
.setTimeZoneOffsetInMins(-4 * 60)
.setOnChangeAction(CardService.newAction()
.setFunctionName("handleDateTimeChange"));
|
|
El siguiente es un ejemplo de una función de controlador de widget de selector de fecha y hora. Este controlador simplemente da formato y registra una string que representa la fecha y hora que eligió el usuario en un widget de selector de fecha y hora con el ID "myDateTimePickerWidgetID":
function handleDateTimeChange(event) {
var dateTimeInput =
event.commonEventObject.formInputs["myDateTimePickerWidgetID"];
var msSinceEpoch = dateTimeInput.msSinceEpoch;
var hasDate = dateTimeInput.hasDate;
var hasTime = dateTimeInput.hadTime;
// The following requires you to configure the add-on to read user locale
// and timezone.
// See https://developers.google.com/apps-script/add-ons/how-tos/access-user-locale
var userTimezoneId = event.userTimezone.id;
// Format and log the date-time selected using the user's timezone.
var formattedDateTime;
if (hasDate && hasTime) {
formattedDateTime = Utilities.formatDate(
new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd hh:mm:ss");
} else if (hasDate) {
formattedDateTime = Utilities.formatDate(
new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd")
+ ", Time unspecified";
} else if (hasTime) {
formattedDateTime = "Date unspecified, "
+ Utilities.formatDate(
new Date(msSinceEpoch), userTimezoneId, "hh:mm a");
}
if (formattedDateTime) {
console.log(formattedDateTime);
}
}
En la siguiente tabla, se muestran ejemplos de las IU de selección de selectores en computadoras y dispositivos móviles. Cuando se selecciona, el selector de fecha abre una IU de calendario basada en el mes para permitir que el usuario seleccione rápidamente una fecha nueva.
Cuando el usuario selecciona el selector de hora en dispositivos de escritorio, se abre un menú desplegable con una lista de horas separadas en incrementos de 30 minutos. El usuario también puede escribir una hora específica. En los dispositivos móviles, si seleccionas un selector de hora, se abre el selector de hora del "reloj" integrado para dispositivos móviles.
| Computadora de escritorio | Dispositivos móviles |
|---|---|
|
|
|
|
Cuadrícula
Muestra elementos en un diseño de varias columnas con el widget de cuadrícula. Cada elemento puede mostrar una imagen, un título y un subtítulo. Usa opciones adicionales de configuración para establecer el posicionamiento del texto en relación con la imagen de un elemento de la cuadrícula.
Puedes configurar un elemento de la cuadrícula con un identificador que se muestra como parámetro para la acción definida en la cuadrícula.
var gridItem = CardService.newGridItem()
.setIdentifier("item_001")
.setTitle("A grid item")
.setSubtitle("with a subtitle")
.setImage(imageComponent);
var cropStyle = CardService.newImageCropStyle()
.setImageCropType(CardService.ImageCropType.SQUARE);
var borderStyle = CardService.newBorderStyle()
.setType(CardService.BorderType.STROKE)
.setCornerRadius(8)
.setStrokeColor("#00FF00FF");
var imageComponent = CardService.newImageComponent()
.setImageUrl("https://cataas.com/cat?0.001")
.setCropStyle(cropStyle)
.setBorderStyle(borderStyle);
var grid = CardService.newGrid()
.setTitle("My first grid")
.addItem(gridItem)
.setNumColumns(2)
.setOnClickAction(CardService.newAction()
.setFunctionName("handleGridItemClick"));
|
|
Formato del texto
Algunos widgets basados en texto admiten formato HTML de texto simple. Cuando configures el contenido de texto de estos widgets, incluye las etiquetas HTML correspondientes.
En la siguiente tabla, se muestran las etiquetas compatibles y su propósito:
| Formato | Ejemplo | Resultado renderizado |
|---|---|---|
| Negrita | "This is <b>bold</b>." |
Este texto es negrita. |
| Cursiva | "This is <i>italics</i>." |
Se trata de cursiva. |
| Subrayado | "This is <u>underline</u>." |
Esto es subrayado. |
| Tachado | "This is <s>strikethrough</s>." |
Esto es |
| Color de fuente | "This is <font color=\"#FF0000\">red font</text>." |
Esta es la fuente roja. |
| Hipervínculo | "This is a <a href=\"https://www.google.com\">hyperlink</a>." |
Este es un hipervínculo. |
| Tiempo | "This is a time format: <time>2023-02-16 15:00</time>." |
Este es un formato de hora: . |
| Nueva línea | "This is the first line. <br> This is a new line." |
Esta es la primera línea. Esta es una línea nueva. |